+Wed Jan 5 10:23:41 2000 Owen Taylor <otaylor@redhat.com>
+
+ * gtk/tmpl/gtkprogress.sgml: Missing </listitem>, remove extra <para>
+ * gtk/tmpl/gtkobject.sgml: dos2unix
+ * gtk/tmpl/gtkcurve.sgml: missing </para>
+ * gtk/tmpl/gtkarg.sgml: dos2unix, missing </para>
+ * gtk/tmpl/gtkcolorsel.sgml: Missing </listitem>'s
+ * gtk/tmpl/gtksignal.sgml (signal): dos2unix, missing </para>'s
+ * gtk/tmpl/gtkmarshal.sgml: Missing </refsect2>
+
1999-11-16 Damon Chaplin <damon@karuna.freeserve.co.uk>
* gtk/tmpl/gtkmenubar.sgml: fixed minor error - using <em>.
-<!-- ##### SECTION Title ##### -->\r
-Implementation of Object Properties\r
-\r
-<!-- ##### SECTION Short_Description ##### -->\r
-Utility function to manipulate lists of named, typed arguments.\r
-\r
-<!-- ##### SECTION Long_Description ##### -->\r
-<para>\r
-All the functions in here are marked a Non-public.\r
-We describe it anyway because it is occasionally useful\r
-to understand how the work is done.\r
-</para>\r
-<para>\r
-Arguments are a way of describing a named parameter to a function.\r
-They have two important roles within gtk+:\r
-<itemizedlist>\r
-<listitem>\r
-<para>\r
-they describe <wordasword>object properties</wordasword>.\r
-This means that they present an interface to get and set a named-type\r
-for any type of object in a consistent way.\r
-(All the relevant functions to do this start with gtk_object_set\r
-or gtk_object_get).\r
-</para>\r
-</listitem>\r
-<listitem>\r
-<para>\r
-they describe <wordasword>signal arguments</wordasword>.\r
-This is a lot less often needed but still useful.\r
-Usually if you are just emitting or creating a particular signal\r
-it is more convenient to just use gtk_signal_emit() or gtk_signal_new().\r
-However if you are writing a function to emit or create an arbitrary\r
-signal, you must use gtk_signal_emitv() or gtk_signal_newv().\r
-</para>\r
-</listitem>\r
-</itemizedlist>\r
-\r
-\r
-<!-- ##### SECTION See_Also ##### -->\r
-<para>\r
-#GtkObject.\r
-</para>\r
-\r
-<!-- ##### STRUCT GtkArgInfo ##### -->\r
-<para>\r
-A structure containing information about the argument.\r
-Returned by gtk_arg_get_info().\r
-</para>\r
-\r
-@class_type: if the argument is an object, this is the object class type.\r
-@name: the name of the argument.\r
-@type: the type of the argument; it may be an object's type\r
-or a fundamental type.\r
-@arg_flags: flags applicable to the argument (i.e. readable, writable,\r
-and whether it needs to be constructed).\r
-@full_name: the object name and argument name separated by ::,\r
-e.g. "GtkObject::user_data" or "GtkButton::label".\r
-@arg_id: the unique argument identified.\r
-@seq_id: ???\r
-\r
-<!-- ##### FUNCTION gtk_arg_new ##### -->\r
-<para>\r
-Creates a new argument of a certain type, set to 0 or NULL.\r
-</para>\r
-\r
-@arg_type: the type of the argument.\r
-@Returns: the newly created #GtkArg.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_arg_copy ##### -->\r
-<para>\r
-It will either copy data into an existing argument or allocate a new argument\r
-and copy the data. Strings are duplicated. All other pointers and\r
-values are copied (shallowly-- that is the pointers themselves are\r
-copied, not the data they point to.)\r
-</para>\r
-<para>\r
-You should call gtk_arg_reset() on dest_arg before calling this\r
-if the argument may contain string data that you want freed.\r
-</para>\r
-\r
-@src_arg: the argument to duplicate.\r
-@dest_arg: the argument to copy over (or NULL to create a new #GtkArg).\r
-@Returns: the new #GtkArg (or dest_arg, if it was not NULL).\r
-\r
-\r
-<!-- ##### FUNCTION gtk_arg_free ##### -->\r
-<para>\r
-Frees the argument, and optionally its contents.\r
-</para>\r
-\r
-@arg: the argument to free.\r
-@free_contents: whether to free the string, if it is a string.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_args_collect ##### -->\r
-<para>\r
-Private: given a hashtable of argument information it takes a vararg\r
-list and parses it into arguments (in the form of lists of #GtkArgs\r
-and lists of #GtkArgInfos.\r
-</para>\r
-<para>\r
-The list of arguments starts with first_arg_name then the first argument's\r
-value. Followed by any number of additional name/argument pairs,\r
-terminated with NULL.\r
-</para>\r
-\r
-@object_type: the type of object we are collecting arguments for.\r
-@arg_info_hash_table: a hashtable mapping from names of arguments\r
-to their #GtkArgInfos.\r
-@arg_list_p: a returned list of arguments obtained from parsing the\r
-varargs.\r
-@info_list_p: a returned list of the #GtkArgInfos.\r
-@first_arg_name: the name of the first argument.\r
-@var_args: a va_list containing the value of the first argument,\r
-followed by name/value pairs, followed by NULL.\r
-@Returns: an error message on failure, or NULL otherwise.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_args_collect_cleanup ##### -->\r
-<para>\r
-Private: erase lists of arguments returned from gtk_args_collect().\r
-</para>\r
-\r
-@arg_list: arg_list_p returned from gtk_args_collect().\r
-@info_list: info_list_p returned from gtk_args_collect().\r
-\r
-\r
-<!-- ##### FUNCTION gtk_arg_get_info ##### -->\r
-<para>\r
-Private: get information about an argument.\r
-</para>\r
-\r
-@object_type: the type of object.\r
-@arg_info_hash_table: the hashtable of #GtkArgInfos.\r
-@arg_name: the name of the argument to lookup.\r
-@info_p: the argument info.\r
-@Returns: an error message on failure, or NULL otherwise.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_arg_type_new_static ##### -->\r
-<para>\r
-Create a new argument registered with a class.\r
-</para>\r
-\r
-@base_class_type: the basic type having the arguments, almost alway\r
-GTK_TYPE_OBJECT, except if your defining a different type argument\r
-that gets a different namespace. #GtkContainer does this to define\r
-per-child arguments of the container.\r
-@arg_name: name of the argument to create. (must be a static constant string)\r
-@class_n_args_offset: offset into the base class structure that tells\r
-the number of arguments.\r
-@arg_info_hash_table: hashtable of #GtkArgInfos.\r
-@arg_type: type of the argument.\r
-@arg_flags: flags of the argument.\r
-@arg_id: ???\r
-@Returns: the new #GtkArgInfo.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_args_query ##### -->\r
-<para>\r
-Private: from a class type and its arginfo hashtable,\r
-get an array of #GtkArgs that this object accepts.\r
-</para>\r
-\r
-@class_type: the class type.\r
-@arg_info_hash_table: the hashtable of #GtkArgInfos.\r
-@arg_flags: returned array of argument flags.\r
-@n_args_p: the number of arguments this object accepts.\r
-@Returns: the array of arguments (or NULL on error).\r
-\r
-\r
-<!-- ##### FUNCTION gtk_arg_name_strip_type ##### -->\r
-<para>\r
-Given a fully qualified argument name (e.g. "GtkButton::label")\r
-it returns just the argument name (e.g. "label") unless\r
-the argument name was invalid, in which case it returns NULL.\r
-</para>\r
-\r
-@arg_name: the fully-qualified argument name.\r
-@Returns: the base argument name.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_arg_info_equal ##### -->\r
-<para>\r
-A #GCompareFunc for hashing #GtkArgInfos.\r
-</para>\r
-\r
-@arg_info_1: a #GtkArgInfo.\r
-@arg_info_2: a #GtkArgInfo.\r
-@Returns: whether the arguments are the same.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_arg_info_hash ##### -->\r
-<para>\r
-A #GHashFunc for hashing #GtkArgInfos.\r
-</para>\r
-\r
-@arg_info: a #GtkArgInfo.\r
-@Returns: a hash value for that #GtkArgInfo.\r
-\r
-\r
+<!-- ##### SECTION Title ##### -->
+Implementation of Object Properties
+
+<!-- ##### SECTION Short_Description ##### -->
+Utility function to manipulate lists of named, typed arguments.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+All the functions in here are marked a Non-public.
+We describe it anyway because it is occasionally useful
+to understand how the work is done.
+</para>
+<para>
+Arguments are a way of describing a named parameter to a function.
+They have two important roles within gtk+:
+<itemizedlist>
+<listitem>
+<para>
+they describe <wordasword>object properties</wordasword>.
+This means that they present an interface to get and set a named-type
+for any type of object in a consistent way.
+(All the relevant functions to do this start with gtk_object_set
+or gtk_object_get).
+</para>
+</listitem>
+<listitem>
+<para>
+they describe <wordasword>signal arguments</wordasword>.
+This is a lot less often needed but still useful.
+Usually if you are just emitting or creating a particular signal
+it is more convenient to just use gtk_signal_emit() or gtk_signal_new().
+However if you are writing a function to emit or create an arbitrary
+signal, you must use gtk_signal_emitv() or gtk_signal_newv().
+</para>
+</listitem>
+</itemizedlist>
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkObject.
+</para>
+
+<!-- ##### STRUCT GtkArgInfo ##### -->
+<para>
+A structure containing information about the argument.
+Returned by gtk_arg_get_info().
+</para>
+
+@class_type: if the argument is an object, this is the object class type.
+@name: the name of the argument.
+@type: the type of the argument; it may be an object's type
+or a fundamental type.
+@arg_flags: flags applicable to the argument (i.e. readable, writable,
+and whether it needs to be constructed).
+@full_name: the object name and argument name separated by ::,
+e.g. "GtkObject::user_data" or "GtkButton::label".
+@arg_id: the unique argument identified.
+@seq_id: ???
+
+<!-- ##### FUNCTION gtk_arg_new ##### -->
+<para>
+Creates a new argument of a certain type, set to 0 or NULL.
+</para>
+
+@arg_type: the type of the argument.
+@Returns: the newly created #GtkArg.
+
+
+<!-- ##### FUNCTION gtk_arg_copy ##### -->
+<para>
+It will either copy data into an existing argument or allocate a new argument
+and copy the data. Strings are duplicated. All other pointers and
+values are copied (shallowly-- that is the pointers themselves are
+copied, not the data they point to.)
+</para>
+<para>
+You should call gtk_arg_reset() on dest_arg before calling this
+if the argument may contain string data that you want freed.
+</para>
+
+@src_arg: the argument to duplicate.
+@dest_arg: the argument to copy over (or NULL to create a new #GtkArg).
+@Returns: the new #GtkArg (or dest_arg, if it was not NULL).
+
+
+<!-- ##### FUNCTION gtk_arg_free ##### -->
+<para>
+Frees the argument, and optionally its contents.
+</para>
+
+@arg: the argument to free.
+@free_contents: whether to free the string, if it is a string.
+
+
+<!-- ##### FUNCTION gtk_args_collect ##### -->
+<para>
+Private: given a hashtable of argument information it takes a vararg
+list and parses it into arguments (in the form of lists of #GtkArgs
+and lists of #GtkArgInfos.
+</para>
+<para>
+The list of arguments starts with first_arg_name then the first argument's
+value. Followed by any number of additional name/argument pairs,
+terminated with NULL.
+</para>
+
+@object_type: the type of object we are collecting arguments for.
+@arg_info_hash_table: a hashtable mapping from names of arguments
+to their #GtkArgInfos.
+@arg_list_p: a returned list of arguments obtained from parsing the
+varargs.
+@info_list_p: a returned list of the #GtkArgInfos.
+@first_arg_name: the name of the first argument.
+@var_args: a va_list containing the value of the first argument,
+followed by name/value pairs, followed by NULL.
+@Returns: an error message on failure, or NULL otherwise.
+
+
+<!-- ##### FUNCTION gtk_args_collect_cleanup ##### -->
+<para>
+Private: erase lists of arguments returned from gtk_args_collect().
+</para>
+
+@arg_list: arg_list_p returned from gtk_args_collect().
+@info_list: info_list_p returned from gtk_args_collect().
+
+
+<!-- ##### FUNCTION gtk_arg_get_info ##### -->
+<para>
+Private: get information about an argument.
+</para>
+
+@object_type: the type of object.
+@arg_info_hash_table: the hashtable of #GtkArgInfos.
+@arg_name: the name of the argument to lookup.
+@info_p: the argument info.
+@Returns: an error message on failure, or NULL otherwise.
+
+
+<!-- ##### FUNCTION gtk_arg_type_new_static ##### -->
+<para>
+Create a new argument registered with a class.
+</para>
+
+@base_class_type: the basic type having the arguments, almost alway
+GTK_TYPE_OBJECT, except if your defining a different type argument
+that gets a different namespace. #GtkContainer does this to define
+per-child arguments of the container.
+@arg_name: name of the argument to create. (must be a static constant string)
+@class_n_args_offset: offset into the base class structure that tells
+the number of arguments.
+@arg_info_hash_table: hashtable of #GtkArgInfos.
+@arg_type: type of the argument.
+@arg_flags: flags of the argument.
+@arg_id: ???
+@Returns: the new #GtkArgInfo.
+
+
+<!-- ##### FUNCTION gtk_args_query ##### -->
+<para>
+Private: from a class type and its arginfo hashtable,
+get an array of #GtkArgs that this object accepts.
+</para>
+
+@class_type: the class type.
+@arg_info_hash_table: the hashtable of #GtkArgInfos.
+@arg_flags: returned array of argument flags.
+@n_args_p: the number of arguments this object accepts.
+@Returns: the array of arguments (or NULL on error).
+
+
+<!-- ##### FUNCTION gtk_arg_name_strip_type ##### -->
+<para>
+Given a fully qualified argument name (e.g. "GtkButton::label")
+it returns just the argument name (e.g. "label") unless
+the argument name was invalid, in which case it returns NULL.
+</para>
+
+@arg_name: the fully-qualified argument name.
+@Returns: the base argument name.
+
+
+<!-- ##### FUNCTION gtk_arg_info_equal ##### -->
+<para>
+A #GCompareFunc for hashing #GtkArgInfos.
+</para>
+
+@arg_info_1: a #GtkArgInfo.
+@arg_info_2: a #GtkArgInfo.
+@Returns: whether the arguments are the same.
+
+
+<!-- ##### FUNCTION gtk_arg_info_hash ##### -->
+<para>
+A #GHashFunc for hashing #GtkArgInfos.
+</para>
+
+@arg_info: a #GtkArgInfo.
+@Returns: a hash value for that #GtkArgInfo.
+
+
%GTK_UPDATE_CONTINUOUS - signals are sent continuously as the color
selection changes.
</para>
+</listitem>
<listitem>
<para>
%GTK_UPDATE_DISCONTINUOUS - signals are sent only when the mouse
button is released.
</para>
+</listitem>
<listitem>
<para>
%GTK_UPDATE_DELAYED - signals are sent when the mouse button is
released or when the mouse has been motionless for a period of
time.
</para>
+</listitem>
</itemizedlist>
</para>
<variablelist>
<varlistentry>
<term>#GtkGammaCurve</term>
-<listitem><para>a subclass for editing gamma curves.
+<listitem><para>a subclass for editing gamma curves.</para>
</listitem>
</varlistentry>
</variablelist>
}
</programlisting>
</para>
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
-<!-- ##### SECTION Title ##### -->\r
-GtkObject\r
-\r
-<!-- ##### SECTION Short_Description ##### -->\r
-The base class of the Gtk type hierarchy.\r
-\r
-<!-- ##### SECTION Long_Description ##### -->\r
-<refsect2>\r
-<title>Description</title>\r
-<para>\r
-GtkObject is the root of the gtk+ type hierarchy. It serves\r
-a similar roles as java's Object class. It is used \r
-by the type-casting system to represent the base composite type.\r
-</para>\r
-<para>\r
-Objects have <wordasword>arguments</wordasword> that are\r
-name/typed-value pairs. \r
-They may be readable or writable (or both or neither).\r
-The special handlers in every object are responsible for\r
-setting and getting these parameters.\r
-If the handler for a given argument <emphasis>must</emphasis>\r
-be called before the object may be used, be sure the\r
-#GTK_ARG_CONSTRUCT or #GTK_ARG_CONSTRUCT_ONLY flags\r
-are set; otherwise they are set only when the user does so.\r
-</para>\r
-<para>\r
-Object also store a simpler association table, sometimes\r
-called the object_data. This is just an efficient mapping from\r
-a fixed set of strings to a gpointer. This can be used as\r
-arbitrary extra members. Notice that each new field name\r
-allocates a new quark, so it is probably best only to use\r
-this for fields with fixed names.\r
-</para>\r
-<para>\r
-The primary difference between object_data and arguments is that\r
-the object defines two functions which set and get each type of argument.\r
-The object just has a table to store its object data in: it does not\r
-receive notice when data changes.\r
-</para>\r
-<para>\r
-Objects are reference counted; this means that we maintain\r
-a count of how many references (usually in the form of a pointer)\r
-are being held to this object.\r
-To indicate that you reference an object, call gtk_object_ref().\r
-The object will not be freed until everyone calls \r
-gtk_object_unref().\r
-</para>\r
-<para>\r
-In order to reduce the chances of a memory leak, gtk+ defines\r
-"floating objects". All objects created with gtk_object_new()\r
-start out floating with a reference count of 1.\r
-In order to reduce that initial reference count you should gtk_object_sink()\r
-them, but usually the parent widget you add the child to will\r
-sink the object. \r
-</para>\r
-<para>So, because gtk_widget_set_parent() sinks the object from\r
-gtk_container_add(), there are no memory leaks in this code:\r
-<informalexample>\r
-<programlisting>\r
- button = gtk_button_new_with_label("Hi Mom!");\r
- gtk_container_add(GTK_CONTAINER(window), button);\r
- /* Button may not be used anymore since we don't retain a reference\r
- * to it. */\r
-</programlisting>\r
-</informalexample>\r
-Likewise, the following code attaches the same adjustment to two\r
-ranges:\r
-<informalexample>\r
-<programlisting>\r
- adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);\r
- gtk_range_set_adjustment(range1, adjustment);\r
- gtk_range_set_adjustment(range2, adjustment);\r
-</programlisting>\r
-</informalexample>\r
-Note that we could put as many set_adjustments as we like: cleanup is easy\r
-because they all retain a reference but only one sinks the initial reference\r
-count. If it is possible for "range1" to stop retaining its reference\r
-then we need to enclose the lines using "adjustment" with ref/unref\r
-to guarantee the the object won't be deleted:\r
-<informalexample>\r
-<programlisting>\r
- adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);\r
- gtk_object_ref(GTK_OBJECT(adjustment));\r
- gtk_range_set_adjustment(range1, adjustment);\r
- gtk_range_set_adjustment(range1, another_adjustment);\r
- /* With the initial reference, `adjustment' would have\r
- * been deleted as `range1' lost its reference to it. */\r
- gtk_range_set_adjustment(range2, adjustment);\r
- gtk_object_unref(GTK_OBJECT(adjustment));\r
-</programlisting>\r
-</informalexample>\r
-</para>\r
-<para>\r
-Be careful with reference counting: if two objects reference eachother\r
-then they will always have at least reference count 1, even if\r
-there are no other pointers to them. This means that they\r
-will never be freed. More precisely, you must be certain that\r
-your references <emphasis>never</emphasis> can form cycles.\r
-</para>\r
-<para>\r
-If you find yourself forming cyclic references, perhaps you\r
-can convert some of them to <wordasword>weak-references</wordasword>.\r
-A weak-reference is one that holds a pointer to an object,\r
-but doesn't increase the reference count. To insure\r
-the object is valid when the referer tries to use it,\r
-the referer registers a callback that will be invoked\r
-after the object has been destroyed (but before its memory is actually\r
-deallocated). This callback must prevent the weak-reference from\r
-being used again.\r
-</para>\r
-</refsect2>\r
-<refsect2>\r
-<title>Brief Glossary</title>\r
-<variablelist>\r
-\r
-<varlistentry>\r
-<term>argument</term>\r
-<listitem><para>\r
-A typed-variable identified by ObjectType::argument_name. It may be\r
-readable, writable, both or none. For example,\r
-"GtkButton::label" is a read/write string-valued argument.\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>constructed</term>\r
-<listitem><para>\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>destroyed</term>\r
-<listitem><para>\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>finalization</term>\r
-<listitem><para>\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>floating</term>\r
-<listitem><para>\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>object data</term>\r
-<listitem><para>\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>reference count</term>\r
-<listitem><para>\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>weak-reference</term>\r
-<listitem><para>\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-</variablelist>\r
-</refsect2>\r
-\r
-<!-- ##### SECTION See_Also ##### -->\r
-<para>\r
-GtkType, GtkArg, gtk-signals.\r
-</para>\r
-\r
-<!-- ##### STRUCT GtkObject ##### -->\r
-<para>\r
-The object itself. You should never use these members directly-\r
-instead you the accessing macros.\r
-</para>\r
-\r
-@klass: a pointer to the GtkObjectClass (or deriver) which contains \r
-the methods defined by this object.\r
-@flags: the state of the object: whether it has been constructed\r
-or destroyed, for example.\r
-@ref_count: a reference count. It is incremented when new\r
-pointers to this object are made, and decremented when the\r
-pointers are deleted. When the reference count\r
-returns to 0, the object is deleted. By default, objects\r
-have reference count 0 when created.\r
-@object_data: \r
-\r
-<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->\r
-<para>\r
-Get the type of an object.\r
-</para>\r
-\r
-@obj: the object whose type we wish to get.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->\r
-<para>\r
-Get the array of signals defined for this object.\r
-</para>\r
-\r
-@obj: the object to fetch the signals from.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->\r
-<para>\r
-Get the number of signals defined by this object.\r
-</para>\r
-\r
-@obj: the object to query.\r
-\r
-\r
-<!-- ##### ENUM GtkObjectFlags ##### -->\r
-<para>\r
-Tells about the state of the object.\r
-</para>\r
-\r
-@GTK_DESTROYED: the GtkObject has had gtk_object_destroyed() invoked on it\r
-and is processing the shutdown callback.\r
-@GTK_FLOATING: whether the object is orphaned. Objects that take\r
-strong hold of an object may gtk_object_sink() it, after obtaining\r
-there own references, if they believe they are nearly primary\r
-ownership of the object.\r
-GTK_CONNECTED: refers to whether are signals are connected to this\r
-object.\r
-@GTK_CONSTRUCTED: refers to whether the arguments for this object are\r
-ready.\r
-\r
-<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->\r
-<para>\r
-Get the #GtkObjectFlags for an object without directly\r
-accessing its members.\r
-</para>\r
-\r
-@obj: the object whose flags are returned.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->\r
-<para>\r
-Test whether a GtkObject has had gtk_object_destroyed() invoked on it.\r
-</para>\r
-\r
-@obj: the object to examine.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->\r
-<para>\r
-When an object is created, it has an initial reference count\r
-of 1 and is floating. <wordasword>Sinking</wordasword> the object \r
-refers to decrementing that original reference count.\r
-</para>\r
-\r
-@obj: the object to examine.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->\r
-<para>\r
-Test whether a GtkObject has had a signal connected to it.\r
-</para>\r
-\r
-@obj: the object to examine.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->\r
-<para>\r
-Test whether a GtkObject's arguments have been prepared.\r
-</para>\r
-\r
-@obj: the object to examine.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->\r
-<para>\r
-Turn on certain object flags. (Private)\r
-</para>\r
-\r
-@obj: the object to affect.\r
-@flag: the flags to set.\r
-\r
-\r
-<!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->\r
-<para>\r
-Turn off certain object flags. (Private)\r
-</para>\r
-\r
-@obj: the object to affect.\r
-@flag: the flags to unset.\r
-\r
-\r
-<!-- ##### ENUM GtkArgFlags ##### -->\r
-<para>\r
-Possible flags indicating how an argument should be treated.\r
-</para>\r
-\r
-@GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)\r
-@GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)\r
-@GTK_ARG_CONSTRUCT: the argument needs construction.\r
-@GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will\r
-be set once during object creation), but is otherwise cannot be\r
-set. Hence this flag is not allowed with #GTK_ARG_WRITABLE,\r
-and is redundant with #GTK_ARG_CONSTRUCT.\r
-@GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)\r
-each child. Used by #GtkContainer.\r
-@GTK_ARG_MASK: the bitwise-OR of all the flags.\r
-@GTK_ARG_READWRITE: the argument is readable and writable.\r
-\r
-<!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->\r
-<para>\r
-Define a signal-handler for a new signal on an already defined\r
-object.\r
-</para>\r
-<para>\r
-See the signal documentation for more general information.\r
-</para>\r
-\r
-@klass: the object class to define the signal for.\r
-@name: the name of the signal.\r
-@signal_flags: the default emission behavior for the signal.\r
-See gtk_signal_new().\r
-@marshaller: a function that will take an array of GtkArgs\r
-and invoke the appropriate handler with the normal calling\r
-conventions.\r
-@return_val: specify the return-value type for the signal\r
-(or GTK_TYPE_NONE for no return-value).\r
-@nparams: specify the number of parameters the signal\r
-receives from the caller of gtk_signal_emit().\r
-@Varargs: list of nparams #GtkTypes to pass to the signal handlers.\r
-@Returns: the signal id. (See #GtkSignals)\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->\r
-<para>\r
-Define a signal-handler for a new signal on an already defined\r
-object.\r
-</para>\r
-\r
-@klass: the object class to define the signal for.\r
-@name: the name of the signal.\r
-@signal_flags: the default emission behavior for the signal.\r
-See gtk_signal_new().\r
-@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array\r
-of arguments, and invokes the function using the appropriate\r
-calling conventions. Usually just select a function\r
-out of gtkmarshal.h.\r
-@return_val: specify the return-value type for the signal (possibly\r
-#GTK_TYPE_NONE).\r
-@nparams: specify the number of parameters the signal\r
-receives from the caller of gtk_signal_emit().\r
-@params: array of #GtkTypes the signal handlers for this signal\r
-should have in their prototype (of length nparams).\r
-@Returns: the signal id. (See #GtkSignals)\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_new ##### -->\r
-<para>\r
-Construct an object given its arguments, enumerated in the call to the\r
-function.\r
-</para>\r
-\r
-@type: the type identifying this object. Returned by gtk_type_unique()\r
-although (for a properly-written object it should be accessible through\r
-#GTK_TYPE_FOO.)\r
-@first_arg_name: name of the first argument to set when constructing\r
-the object.\r
-@Varargs: the first argument's value, followed by any number of\r
-name/argument-value pairs, terminated with NULL.\r
-@Returns: the new GtkObject.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_newv ##### -->\r
-<para>\r
-Construct an object with an array of arguments.\r
-</para>\r
-\r
-@object_type: the type of the object to create.\r
-@n_args: the number of arguments to set.\r
-@args: an array of n_args arguments (which are name and value pairs).\r
-@Returns: the new GtkObject.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_constructed ##### -->\r
-<para>\r
-Mark an allocated object as constructed.\r
-This is used for situations\r
-that require precise control of the construction process.\r
-</para>\r
-<para>\r
-This is done when gtk_object_default_construct() is inadequate.\r
-In #GtkCList the need arises because #GtkCList does construction work that\r
-must happen <emphasis>after</emphasis> its derivers. This work\r
-cannot be done in an initializer function, so an alternate\r
-constructor is mandatory. It calls gtk_object_constructed() to\r
-indicate it has done its job, so that no other constructor will\r
-be invoked.\r
-</para>\r
-<para>\r
-Normally this function is just automatically run from\r
-gtk_object_default_construct().\r
-</para>\r
-\r
-@object: object which has been constructed. This is usually\r
-done automatically by gtk_object_new() and gtk_object_newv().\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_default_construct ##### -->\r
-<para>\r
-This function is called to construct arguments that haven't been initialized\r
-but have the #GTK_ARG_CONSTRUCT flag set.\r
-</para>\r
-<para>\r
-All number arguments are set to 0. All pointers and strings\r
-are set to NULL.\r
-</para>\r
-<para>\r
-Normally invoked by gtk_object_new() automatically; gtk_type_new() can\r
-be used to bypass it.\r
-</para>\r
-\r
-@object: the object to initialize.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_sink ##### -->\r
-<para>\r
-Decrement the initial count given to the object.\r
-Additional invocations have no effect.\r
-</para>\r
-<para>\r
-This is designed to free the user from worrying about\r
-dereferencing an object that they have just created.\r
-So long as the object is sunk at some point, the reference count\r
-will be set properly.\r
-</para>\r
-<para>\r
-furthermore it may be sunk multiple times.\r
-Only the first time will actually dereference.\r
-</para>\r
-<para>\r
-The basic outline is: when you create an object it is floating.\r
-Setting its parent causes it to be sunk, however its parent\r
-has obtained a reference, so its reference count is one.\r
-</para>\r
-\r
-@object: the object to sink.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_ref ##### -->\r
-<para>\r
-Increase the reference count of the object.\r
-</para>\r
-\r
-@object: the object to reference.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_unref ##### -->\r
-<para>\r
-Decrease the reference count of an object. When its reference\r
-count drops to 0, the object is deleted.\r
-</para>\r
-<para>\r
-If it was not already destroyed, it will be, with gtk_object_destroy(),\r
-then weak links are notified, then the object-data is freed\r
-and the memory for the object itself is freed using gtk_type_free().\r
-</para>\r
-\r
-@object: the object to dereference.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_weakref ##### -->\r
-<para>\r
-Adds a weak reference callback to an object.\r
-</para>\r
-<para>\r
-Weak references are a mechanism to safely keep a pointer to\r
-an object without using the reference counting\r
-mechansim. They use a callback function to receive\r
-notice that the object is about to be freed (aka finalized).\r
-This happens <emphasis>after</emphasis> the destroy\r
-callback has been run.\r
-</para>\r
-\r
-@object: object to weakly reference.\r
-@notify: callback to invoke before the object is freed.\r
-@data: extra data to pass to #notify.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_weakunref ##### -->\r
-<para>\r
-Removes a weak reference callback to an object.\r
-</para>\r
-\r
-@object: object stop weakly referencing.\r
-@notify: callback to search for.\r
-@data: data to search for.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_destroy ##### -->\r
-<para>\r
-Calls the object's shutdown handler.\r
-</para>\r
-<para>\r
-The memory for the object itself won't be deleted until\r
-its reference count drops to 0, though.\r
-See gtk_object_unref().\r
-</para>\r
-\r
-@object: the object to destroy.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_getv ##### -->\r
-<para>\r
-Gets an array of argument values from an object.\r
-</para>\r
-\r
-@object: the object to get arguments from.\r
-@n_args: the number of arguments to query.\r
-@args: the arguments to fill in.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_set ##### -->\r
-<para>\r
-This function sets multiple arguments of an object.\r
-</para>\r
-<para>\r
-It takes an object, then a list of name/value pairs\r
-in a list, followed by NULL.\r
-</para>\r
-<para>\r
-<informalexample>\r
-<programlisting>\r
-void set_box_properties(GtkBox* box)\r
-{\r
- gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,\r
- "spacing", 8,\r
- NULL);\r
-}\r
-</programlisting>\r
-</informalexample>\r
-</para>\r
-\r
-\r
-@object: the object whose arguments should be set.\r
-@first_arg_name: the name of the first argument to set.\r
-@Varargs: the value of the first argument, followed optionally\r
-by more name/value pairs, followed by NULL.\r
-\r
-<!-- ##### FUNCTION gtk_object_setv ##### -->\r
-<para>\r
-Set an array of arguments.\r
-</para>\r
-\r
-@object: the object whose arguments should be set.\r
-@n_args: the number of arguments to set.\r
-@args: the desired values, as an array of #GtkArgs (which contain \r
-the names, types, and values of the arguments).\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_query_args ##### -->\r
-<para>\r
-Get all the arguments that may be used for a given type.\r
-</para>\r
-<para>\r
-In Java, this type of mechanism is called \r
-<wordasword>introspection</wordasword>. It is used by applications\r
-like Glade, that have to determine what can be done to an object\r
-at run-time.\r
-</para>\r
-\r
-@class_type: the GtkType of the ObjectClass\r
-(returned from GTK_OBJECT_CLASS(class)->type for example).\r
-@arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to\r
-each argument. You must g_free() this if you request it.\r
-@n_args: the number of arguments is returned in this field.\r
-@Returns: an array of arguments, that you must deallocate with g_free().\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_set_data ##### -->\r
-<para>\r
-Each object carries around a table of associations from\r
-strings to pointers. This function lets you set an association.\r
-</para>\r
-<para>\r
-If the object already had an association with that name,\r
-the old association will be destroyed.\r
-</para>\r
-\r
-@object: object containing the associations.\r
-@key: name of the key.\r
-@data: data to associate with that key.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_set_data_full ##### -->\r
-<para>\r
-Like gtk_object_set_data() except it adds notification\r
-for when the association is destroyed, either by\r
-gtk_object_remove_data() or when the object is destroyed.\r
-</para>\r
-\r
-@object: object containing the associations.\r
-@key: name of the key.\r
-@data: data to associate with that key.\r
-@destroy: function to call when the association is destroyed.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_remove_data ##### -->\r
-<para>\r
-Remove a specified datum from the object's data associations (the object_data).\r
-Subsequent calls to gtk_object_get_data() will return NULL.\r
-</para>\r
-<para>\r
-If you specified a destroy handler with gtk_object_set_data_full(),\r
-it will be invoked.\r
-</para>\r
-\r
-\r
-@object: the object maintaining the association.\r
-@key: name of the key for that association.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_get_data ##### -->\r
-<para>\r
-Get a named field from the object's table of associations (the object_data).\r
-</para>\r
-\r
-@object: the object maintaining the associations.\r
-@key: name of the key for that association.\r
-@Returns: the data if found, or NULL if no such data exists.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->\r
-<para>\r
-Remove a specified datum from the object's data associations (the object_data),\r
-without invoking the association's destroy handler.\r
-</para>\r
-<para>\r
-Just like gtk_object_remove_data() except that any destroy handler\r
-will be ignored.\r
-Therefore this only affects data set using gtk_object_set_data_full().\r
-</para>\r
-\r
-@object: the object maintaining the association.\r
-@key: name of the key for that association.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_set_user_data ##### -->\r
-<para>\r
-For convenience, every object offers a generic user data\r
-pointer. The function set it.\r
-</para>\r
-<para>\r
-This function is equivalent to:\r
-<informalexample>\r
-<programlisting>\r
- gtk_object_set_data(object, "user_data", data);\r
-</programlisting>\r
-</informalexample>\r
-</para>\r
-\r
-@object: the object whose user data should be set.\r
-@data: the new value for the user data.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_get_user_data ##### -->\r
-<para>\r
-Get the object's user data pointer.\r
-</para>\r
-<para>\r
-This is intended to be a pointer for your convenience in\r
-writing applications.\r
-</para>\r
-\r
-@object: the object.\r
-@Returns: the user data field for object.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_class_add_signals ##### -->\r
-<para>\r
-Add an array of signals to a #GtkObjectClass.\r
-Usually this is called when registering a new type of object.\r
-</para>\r
-\r
-@klass: the object class to append signals to.\r
-@signals: the signals to append.\r
-@nsignals: the number of signals being appended.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_add_arg_type ##### -->\r
-<para>\r
-Add a new type of argument to an object class.\r
-Usually this is called when registering a new type of object.\r
-</para>\r
-\r
-@arg_name: fully qualify object name, for example GtkObject::user_data.\r
-@arg_type: type of the argument.\r
-@arg_flags: bitwise-OR of the #GtkArgFlags enum. (Whether the argument is\r
-settable or gettable, whether it is set when the object is constructed.)\r
-@arg_id: an internal number, passed in from here to the "set_arg" and\r
-"get_arg" handlers of the object.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->\r
-<para>\r
-Just like gtk_object_set_data() except that it takes\r
-a #GQuark instead of a string, so it is slightly faster.\r
-</para>\r
-<para>\r
-Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
-to get an id from a string.\r
-</para>\r
-\r
-@object: object containing the associations.\r
-@data_id: quark of the key.\r
-@data: data to associate with that key.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->\r
-<para>\r
-Just like gtk_object_set_data_full() except that it takes\r
-a #GQuark instead of a string, so it is slightly faster.\r
-</para>\r
-<para>\r
-Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
-to get an id from a string.\r
-</para>\r
-\r
-@object: object containing the associations.\r
-@data_id: quark of the key.\r
-@data: data to associate with that key.\r
-@destroy: function to call when the association is destroyed.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->\r
-<para>\r
-Just like gtk_object_get_data() except that it takes\r
-a #GQuark instead of a string, so it is slightly faster.\r
-</para>\r
-<para>\r
-Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
-to get an id from a string.\r
-</para>\r
-\r
-@object: object containing the associations.\r
-@data_id: quark of the key.\r
-@Returns: the data if found, or NULL if no such data exists.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->\r
-<para>\r
-Just like gtk_object_remove_data() except that it takes\r
-a #GQuark instead of a string, so it is slightly faster.\r
-</para>\r
-<para>\r
-Remove a specified datum from the object's data associations.\r
-Subsequent calls to gtk_object_get_data() will return NULL.\r
-</para>\r
-<para>\r
-Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
-to get an id from a string.\r
-</para>\r
-\r
-@object: object containing the associations.\r
-@data_id: quark of the key.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->\r
-<para>\r
-Just like gtk_object_remove_no_notify() except that it takes\r
-a #GQuark instead of a string, so it is slightly faster.\r
-</para>\r
-<para>\r
-Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
-to get an id from a string.\r
-</para>\r
-\r
-@object: object containing the associations.\r
-@data_id: quark of the key.\r
-\r
-\r
-<!-- ##### MACRO gtk_object_data_try_key ##### -->\r
-<para>\r
-Sees whether a certain quark exists.\r
-Returns that quark if so.\r
-</para>\r
-<para>\r
-Although this is currently the same as g_quark_try_string(),\r
-it might someday be different, for example, if GQuarks\r
-and object data are converted to separate mechanisms,\r
-so it is good to use this macro.\r
-</para>\r
-\r
-\r
-\r
-<!-- ##### MACRO gtk_object_data_force_id ##### -->\r
-<para>\r
-Makes a quark from a string, possibly allocating a new quark.\r
-</para>\r
-<para>\r
-Although this is currently the same as g_quark_from_string(),\r
-it might someday be different, for example, if GQuarks\r
-and object data are converted to separate mechanisms,\r
-so it is good to use this macro.\r
-</para>\r
-\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_arg_set ##### -->\r
-<para>\r
-Private function to set an argument and argument info to an object.\r
-</para>\r
-\r
-@object: the object whose argument should be set.\r
-@arg: the argument.\r
-@info: infomation about this type of argument in general.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_arg_get ##### -->\r
-<para>\r
-Private function to get an argument and argument info from an object.\r
-</para>\r
-\r
-@object: the object whose argument should be retrieved.\r
-@arg: the argument, for the name on input, the rest is filled on output.\r
-@info: a #GtkArgInfo structure to optionally fill in.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_args_collect ##### -->\r
-<para>\r
-Private: Gets an array of #GtkArgs from a va_list C structure.\r
-</para>\r
-<para>\r
-\r
-@object_type: the type of object to collect arguments for.\r
-@arg_list_p: pointer to be filled in with a list of parsed arguments.\r
-@info_list_p: optional pointer for a returned list #GtkArgInfos.\r
-@first_arg_name: name of first argument.\r
-@var_args: value of first argument, followed by more key/value pairs,\r
-terminated by NULL.\r
-@Returns: an error message, or NULL on success.\r
-It is the caller's responsibility to call g_free() in the event of error.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_object_arg_get_info ##### -->\r
-<para>\r
-Query information about an argument type.\r
-</para>\r
-\r
-@object_type: type of object to query about.\r
-@arg_name: name of the argument.\r
-@info_p: pointer to be filled in with a pointer to the GtkArgInfo.\r
-@Returns: an error message, or NULL on success.\r
-It is the caller's responsibility to call g_free() in the event of error.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_trace_referencing ##### -->\r
-<para>\r
-Private: print debugging information while doing a gtk_object_ref() or \r
-a gtk_object_unref().\r
-</para>\r
-\r
-@object: object to reference or unreference.\r
-@func: name of caller's function to print (used within macros).\r
-@dummy: unused.\r
-@line: line number (used within macros).\r
-@do_ref: whether to reference or unreference.\r
-\r
-\r
-<!-- ##### SIGNAL GtkObject::destroy ##### -->\r
-<para>\r
-Indicates that an object is being destroyed.\r
-</para>\r
-\r
-@object: the object which received the signal.\r
-\r
-<!-- ##### ARG GtkObject:user_data ##### -->\r
-<para>\r
-A pointer for convenience when programming applications.\r
-</para>\r
-\r
-<!-- ##### ARG GtkObject:signal ##### -->\r
-<para>\r
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
-the signal to the object.\r
-</para>\r
-\r
-<!-- ##### ARG GtkObject:signal_after ##### -->\r
-<para>\r
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
-the signal to the object, so that the signal is always run\r
-after other user handlers and the default handler.\r
-</para>\r
-\r
-<!-- ##### ARG GtkObject:object_signal ##### -->\r
-<para>\r
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
-the signal to the object, so that the user data and objects\r
-and swapped when the signal handler is invoked.\r
-</para>\r
-<para>\r
-This is useful for handlers that are primarily notifying\r
-other objects and could just invoke an already existing function\r
-if the parameters were swapped.\r
-See gtk_signal_connect_object() for more details.\r
-</para>\r
-\r
-<!-- ##### ARG GtkObject:object_signal_after ##### -->\r
-<para>\r
-Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
-the signal to the object, so that the user data and objects\r
-and swapped when the signal handler is invoked,\r
-and so that the handler is invoked after all others.\r
-</para>\r
-<para>\r
-See gtk_signal_connect_object_after() for more details.\r
-</para>\r
-\r
+<!-- ##### SECTION Title ##### -->
+GtkObject
+
+<!-- ##### SECTION Short_Description ##### -->
+The base class of the Gtk type hierarchy.
+
+<!-- ##### SECTION Long_Description ##### -->
+<refsect2>
+<title>Description</title>
+<para>
+GtkObject is the root of the gtk+ type hierarchy. It serves
+a similar roles as java's Object class. It is used
+by the type-casting system to represent the base composite type.
+</para>
+<para>
+Objects have <wordasword>arguments</wordasword> that are
+name/typed-value pairs.
+They may be readable or writable (or both or neither).
+The special handlers in every object are responsible for
+setting and getting these parameters.
+If the handler for a given argument <emphasis>must</emphasis>
+be called before the object may be used, be sure the
+#GTK_ARG_CONSTRUCT or #GTK_ARG_CONSTRUCT_ONLY flags
+are set; otherwise they are set only when the user does so.
+</para>
+<para>
+Object also store a simpler association table, sometimes
+called the object_data. This is just an efficient mapping from
+a fixed set of strings to a gpointer. This can be used as
+arbitrary extra members. Notice that each new field name
+allocates a new quark, so it is probably best only to use
+this for fields with fixed names.
+</para>
+<para>
+The primary difference between object_data and arguments is that
+the object defines two functions which set and get each type of argument.
+The object just has a table to store its object data in: it does not
+receive notice when data changes.
+</para>
+<para>
+Objects are reference counted; this means that we maintain
+a count of how many references (usually in the form of a pointer)
+are being held to this object.
+To indicate that you reference an object, call gtk_object_ref().
+The object will not be freed until everyone calls
+gtk_object_unref().
+</para>
+<para>
+In order to reduce the chances of a memory leak, gtk+ defines
+"floating objects". All objects created with gtk_object_new()
+start out floating with a reference count of 1.
+In order to reduce that initial reference count you should gtk_object_sink()
+them, but usually the parent widget you add the child to will
+sink the object.
+</para>
+<para>So, because gtk_widget_set_parent() sinks the object from
+gtk_container_add(), there are no memory leaks in this code:
+<informalexample>
+<programlisting>
+ button = gtk_button_new_with_label("Hi Mom!");
+ gtk_container_add(GTK_CONTAINER(window), button);
+ /* Button may not be used anymore since we don't retain a reference
+ * to it. */
+</programlisting>
+</informalexample>
+Likewise, the following code attaches the same adjustment to two
+ranges:
+<informalexample>
+<programlisting>
+ adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
+ gtk_range_set_adjustment(range1, adjustment);
+ gtk_range_set_adjustment(range2, adjustment);
+</programlisting>
+</informalexample>
+Note that we could put as many set_adjustments as we like: cleanup is easy
+because they all retain a reference but only one sinks the initial reference
+count. If it is possible for "range1" to stop retaining its reference
+then we need to enclose the lines using "adjustment" with ref/unref
+to guarantee the the object won't be deleted:
+<informalexample>
+<programlisting>
+ adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
+ gtk_object_ref(GTK_OBJECT(adjustment));
+ gtk_range_set_adjustment(range1, adjustment);
+ gtk_range_set_adjustment(range1, another_adjustment);
+ /* With the initial reference, `adjustment' would have
+ * been deleted as `range1' lost its reference to it. */
+ gtk_range_set_adjustment(range2, adjustment);
+ gtk_object_unref(GTK_OBJECT(adjustment));
+</programlisting>
+</informalexample>
+</para>
+<para>
+Be careful with reference counting: if two objects reference eachother
+then they will always have at least reference count 1, even if
+there are no other pointers to them. This means that they
+will never be freed. More precisely, you must be certain that
+your references <emphasis>never</emphasis> can form cycles.
+</para>
+<para>
+If you find yourself forming cyclic references, perhaps you
+can convert some of them to <wordasword>weak-references</wordasword>.
+A weak-reference is one that holds a pointer to an object,
+but doesn't increase the reference count. To insure
+the object is valid when the referer tries to use it,
+the referer registers a callback that will be invoked
+after the object has been destroyed (but before its memory is actually
+deallocated). This callback must prevent the weak-reference from
+being used again.
+</para>
+</refsect2>
+<refsect2>
+<title>Brief Glossary</title>
+<variablelist>
+
+<varlistentry>
+<term>argument</term>
+<listitem><para>
+A typed-variable identified by ObjectType::argument_name. It may be
+readable, writable, both or none. For example,
+"GtkButton::label" is a read/write string-valued argument.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>constructed</term>
+<listitem><para>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>destroyed</term>
+<listitem><para>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>finalization</term>
+<listitem><para>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>floating</term>
+<listitem><para>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>object data</term>
+<listitem><para>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>reference count</term>
+<listitem><para>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>weak-reference</term>
+<listitem><para>
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+GtkType, GtkArg, gtk-signals.
+</para>
+
+<!-- ##### STRUCT GtkObject ##### -->
+<para>
+The object itself. You should never use these members directly-
+instead you the accessing macros.
+</para>
+
+@klass: a pointer to the GtkObjectClass (or deriver) which contains
+the methods defined by this object.
+@flags: the state of the object: whether it has been constructed
+or destroyed, for example.
+@ref_count: a reference count. It is incremented when new
+pointers to this object are made, and decremented when the
+pointers are deleted. When the reference count
+returns to 0, the object is deleted. By default, objects
+have reference count 0 when created.
+@object_data:
+
+<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
+<para>
+Get the type of an object.
+</para>
+
+@obj: the object whose type we wish to get.
+
+
+<!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->
+<para>
+Get the array of signals defined for this object.
+</para>
+
+@obj: the object to fetch the signals from.
+
+
+<!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->
+<para>
+Get the number of signals defined by this object.
+</para>
+
+@obj: the object to query.
+
+
+<!-- ##### ENUM GtkObjectFlags ##### -->
+<para>
+Tells about the state of the object.
+</para>
+
+@GTK_DESTROYED: the GtkObject has had gtk_object_destroyed() invoked on it
+and is processing the shutdown callback.
+@GTK_FLOATING: whether the object is orphaned. Objects that take
+strong hold of an object may gtk_object_sink() it, after obtaining
+there own references, if they believe they are nearly primary
+ownership of the object.
+GTK_CONNECTED: refers to whether are signals are connected to this
+object.
+@GTK_CONSTRUCTED: refers to whether the arguments for this object are
+ready.
+
+<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
+<para>
+Get the #GtkObjectFlags for an object without directly
+accessing its members.
+</para>
+
+@obj: the object whose flags are returned.
+
+
+<!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->
+<para>
+Test whether a GtkObject has had gtk_object_destroyed() invoked on it.
+</para>
+
+@obj: the object to examine.
+
+
+<!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
+<para>
+When an object is created, it has an initial reference count
+of 1 and is floating. <wordasword>Sinking</wordasword> the object
+refers to decrementing that original reference count.
+</para>
+
+@obj: the object to examine.
+
+
+<!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
+<para>
+Test whether a GtkObject has had a signal connected to it.
+</para>
+
+@obj: the object to examine.
+
+
+<!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->
+<para>
+Test whether a GtkObject's arguments have been prepared.
+</para>
+
+@obj: the object to examine.
+
+
+<!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
+<para>
+Turn on certain object flags. (Private)
+</para>
+
+@obj: the object to affect.
+@flag: the flags to set.
+
+
+<!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
+<para>
+Turn off certain object flags. (Private)
+</para>
+
+@obj: the object to affect.
+@flag: the flags to unset.
+
+
+<!-- ##### ENUM GtkArgFlags ##### -->
+<para>
+Possible flags indicating how an argument should be treated.
+</para>
+
+@GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)
+@GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)
+@GTK_ARG_CONSTRUCT: the argument needs construction.
+@GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will
+be set once during object creation), but is otherwise cannot be
+set. Hence this flag is not allowed with #GTK_ARG_WRITABLE,
+and is redundant with #GTK_ARG_CONSTRUCT.
+@GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)
+each child. Used by #GtkContainer.
+@GTK_ARG_MASK: the bitwise-OR of all the flags.
+@GTK_ARG_READWRITE: the argument is readable and writable.
+
+<!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->
+<para>
+Define a signal-handler for a new signal on an already defined
+object.
+</para>
+<para>
+See the signal documentation for more general information.
+</para>
+
+@klass: the object class to define the signal for.
+@name: the name of the signal.
+@signal_flags: the default emission behavior for the signal.
+See gtk_signal_new().
+@marshaller: a function that will take an array of GtkArgs
+and invoke the appropriate handler with the normal calling
+conventions.
+@return_val: specify the return-value type for the signal
+(or GTK_TYPE_NONE for no return-value).
+@nparams: specify the number of parameters the signal
+receives from the caller of gtk_signal_emit().
+@Varargs: list of nparams #GtkTypes to pass to the signal handlers.
+@Returns: the signal id. (See #GtkSignals)
+
+
+<!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->
+<para>
+Define a signal-handler for a new signal on an already defined
+object.
+</para>
+
+@klass: the object class to define the signal for.
+@name: the name of the signal.
+@signal_flags: the default emission behavior for the signal.
+See gtk_signal_new().
+@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array
+of arguments, and invokes the function using the appropriate
+calling conventions. Usually just select a function
+out of gtkmarshal.h.
+@return_val: specify the return-value type for the signal (possibly
+#GTK_TYPE_NONE).
+@nparams: specify the number of parameters the signal
+receives from the caller of gtk_signal_emit().
+@params: array of #GtkTypes the signal handlers for this signal
+should have in their prototype (of length nparams).
+@Returns: the signal id. (See #GtkSignals)
+
+
+<!-- ##### FUNCTION gtk_object_new ##### -->
+<para>
+Construct an object given its arguments, enumerated in the call to the
+function.
+</para>
+
+@type: the type identifying this object. Returned by gtk_type_unique()
+although (for a properly-written object it should be accessible through
+#GTK_TYPE_FOO.)
+@first_arg_name: name of the first argument to set when constructing
+the object.
+@Varargs: the first argument's value, followed by any number of
+name/argument-value pairs, terminated with NULL.
+@Returns: the new GtkObject.
+
+
+<!-- ##### FUNCTION gtk_object_newv ##### -->
+<para>
+Construct an object with an array of arguments.
+</para>
+
+@object_type: the type of the object to create.
+@n_args: the number of arguments to set.
+@args: an array of n_args arguments (which are name and value pairs).
+@Returns: the new GtkObject.
+
+
+<!-- ##### FUNCTION gtk_object_constructed ##### -->
+<para>
+Mark an allocated object as constructed.
+This is used for situations
+that require precise control of the construction process.
+</para>
+<para>
+This is done when gtk_object_default_construct() is inadequate.
+In #GtkCList the need arises because #GtkCList does construction work that
+must happen <emphasis>after</emphasis> its derivers. This work
+cannot be done in an initializer function, so an alternate
+constructor is mandatory. It calls gtk_object_constructed() to
+indicate it has done its job, so that no other constructor will
+be invoked.
+</para>
+<para>
+Normally this function is just automatically run from
+gtk_object_default_construct().
+</para>
+
+@object: object which has been constructed. This is usually
+done automatically by gtk_object_new() and gtk_object_newv().
+
+
+<!-- ##### FUNCTION gtk_object_default_construct ##### -->
+<para>
+This function is called to construct arguments that haven't been initialized
+but have the #GTK_ARG_CONSTRUCT flag set.
+</para>
+<para>
+All number arguments are set to 0. All pointers and strings
+are set to NULL.
+</para>
+<para>
+Normally invoked by gtk_object_new() automatically; gtk_type_new() can
+be used to bypass it.
+</para>
+
+@object: the object to initialize.
+
+
+<!-- ##### FUNCTION gtk_object_sink ##### -->
+<para>
+Decrement the initial count given to the object.
+Additional invocations have no effect.
+</para>
+<para>
+This is designed to free the user from worrying about
+dereferencing an object that they have just created.
+So long as the object is sunk at some point, the reference count
+will be set properly.
+</para>
+<para>
+furthermore it may be sunk multiple times.
+Only the first time will actually dereference.
+</para>
+<para>
+The basic outline is: when you create an object it is floating.
+Setting its parent causes it to be sunk, however its parent
+has obtained a reference, so its reference count is one.
+</para>
+
+@object: the object to sink.
+
+
+<!-- ##### FUNCTION gtk_object_ref ##### -->
+<para>
+Increase the reference count of the object.
+</para>
+
+@object: the object to reference.
+
+
+<!-- ##### FUNCTION gtk_object_unref ##### -->
+<para>
+Decrease the reference count of an object. When its reference
+count drops to 0, the object is deleted.
+</para>
+<para>
+If it was not already destroyed, it will be, with gtk_object_destroy(),
+then weak links are notified, then the object-data is freed
+and the memory for the object itself is freed using gtk_type_free().
+</para>
+
+@object: the object to dereference.
+
+
+<!-- ##### FUNCTION gtk_object_weakref ##### -->
+<para>
+Adds a weak reference callback to an object.
+</para>
+<para>
+Weak references are a mechanism to safely keep a pointer to
+an object without using the reference counting
+mechansim. They use a callback function to receive
+notice that the object is about to be freed (aka finalized).
+This happens <emphasis>after</emphasis> the destroy
+callback has been run.
+</para>
+
+@object: object to weakly reference.
+@notify: callback to invoke before the object is freed.
+@data: extra data to pass to #notify.
+
+
+<!-- ##### FUNCTION gtk_object_weakunref ##### -->
+<para>
+Removes a weak reference callback to an object.
+</para>
+
+@object: object stop weakly referencing.
+@notify: callback to search for.
+@data: data to search for.
+
+
+<!-- ##### FUNCTION gtk_object_destroy ##### -->
+<para>
+Calls the object's shutdown handler.
+</para>
+<para>
+The memory for the object itself won't be deleted until
+its reference count drops to 0, though.
+See gtk_object_unref().
+</para>
+
+@object: the object to destroy.
+
+
+<!-- ##### FUNCTION gtk_object_getv ##### -->
+<para>
+Gets an array of argument values from an object.
+</para>
+
+@object: the object to get arguments from.
+@n_args: the number of arguments to query.
+@args: the arguments to fill in.
+
+
+<!-- ##### FUNCTION gtk_object_set ##### -->
+<para>
+This function sets multiple arguments of an object.
+</para>
+<para>
+It takes an object, then a list of name/value pairs
+in a list, followed by NULL.
+</para>
+<para>
+<informalexample>
+<programlisting>
+void set_box_properties(GtkBox* box)
+{
+ gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,
+ "spacing", 8,
+ NULL);
+}
+</programlisting>
+</informalexample>
+</para>
+
+
+@object: the object whose arguments should be set.
+@first_arg_name: the name of the first argument to set.
+@Varargs: the value of the first argument, followed optionally
+by more name/value pairs, followed by NULL.
+
+<!-- ##### FUNCTION gtk_object_setv ##### -->
+<para>
+Set an array of arguments.
+</para>
+
+@object: the object whose arguments should be set.
+@n_args: the number of arguments to set.
+@args: the desired values, as an array of #GtkArgs (which contain
+the names, types, and values of the arguments).
+
+
+<!-- ##### FUNCTION gtk_object_query_args ##### -->
+<para>
+Get all the arguments that may be used for a given type.
+</para>
+<para>
+In Java, this type of mechanism is called
+<wordasword>introspection</wordasword>. It is used by applications
+like Glade, that have to determine what can be done to an object
+at run-time.
+</para>
+
+@class_type: the GtkType of the ObjectClass
+(returned from GTK_OBJECT_CLASS(class)->type for example).
+@arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to
+each argument. You must g_free() this if you request it.
+@n_args: the number of arguments is returned in this field.
+@Returns: an array of arguments, that you must deallocate with g_free().
+
+
+<!-- ##### FUNCTION gtk_object_set_data ##### -->
+<para>
+Each object carries around a table of associations from
+strings to pointers. This function lets you set an association.
+</para>
+<para>
+If the object already had an association with that name,
+the old association will be destroyed.
+</para>
+
+@object: object containing the associations.
+@key: name of the key.
+@data: data to associate with that key.
+
+
+<!-- ##### FUNCTION gtk_object_set_data_full ##### -->
+<para>
+Like gtk_object_set_data() except it adds notification
+for when the association is destroyed, either by
+gtk_object_remove_data() or when the object is destroyed.
+</para>
+
+@object: object containing the associations.
+@key: name of the key.
+@data: data to associate with that key.
+@destroy: function to call when the association is destroyed.
+
+
+<!-- ##### FUNCTION gtk_object_remove_data ##### -->
+<para>
+Remove a specified datum from the object's data associations (the object_data).
+Subsequent calls to gtk_object_get_data() will return NULL.
+</para>
+<para>
+If you specified a destroy handler with gtk_object_set_data_full(),
+it will be invoked.
+</para>
+
+
+@object: the object maintaining the association.
+@key: name of the key for that association.
+
+
+<!-- ##### FUNCTION gtk_object_get_data ##### -->
+<para>
+Get a named field from the object's table of associations (the object_data).
+</para>
+
+@object: the object maintaining the associations.
+@key: name of the key for that association.
+@Returns: the data if found, or NULL if no such data exists.
+
+
+<!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
+<para>
+Remove a specified datum from the object's data associations (the object_data),
+without invoking the association's destroy handler.
+</para>
+<para>
+Just like gtk_object_remove_data() except that any destroy handler
+will be ignored.
+Therefore this only affects data set using gtk_object_set_data_full().
+</para>
+
+@object: the object maintaining the association.
+@key: name of the key for that association.
+
+
+<!-- ##### FUNCTION gtk_object_set_user_data ##### -->
+<para>
+For convenience, every object offers a generic user data
+pointer. The function set it.
+</para>
+<para>
+This function is equivalent to:
+<informalexample>
+<programlisting>
+ gtk_object_set_data(object, "user_data", data);
+</programlisting>
+</informalexample>
+</para>
+
+@object: the object whose user data should be set.
+@data: the new value for the user data.
+
+
+<!-- ##### FUNCTION gtk_object_get_user_data ##### -->
+<para>
+Get the object's user data pointer.
+</para>
+<para>
+This is intended to be a pointer for your convenience in
+writing applications.
+</para>
+
+@object: the object.
+@Returns: the user data field for object.
+
+
+<!-- ##### FUNCTION gtk_object_class_add_signals ##### -->
+<para>
+Add an array of signals to a #GtkObjectClass.
+Usually this is called when registering a new type of object.
+</para>
+
+@klass: the object class to append signals to.
+@signals: the signals to append.
+@nsignals: the number of signals being appended.
+
+
+<!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
+<para>
+Add a new type of argument to an object class.
+Usually this is called when registering a new type of object.
+</para>
+
+@arg_name: fully qualify object name, for example GtkObject::user_data.
+@arg_type: type of the argument.
+@arg_flags: bitwise-OR of the #GtkArgFlags enum. (Whether the argument is
+settable or gettable, whether it is set when the object is constructed.)
+@arg_id: an internal number, passed in from here to the "set_arg" and
+"get_arg" handlers of the object.
+
+
+<!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
+<para>
+Just like gtk_object_set_data() except that it takes
+a #GQuark instead of a string, so it is slightly faster.
+</para>
+<para>
+Use gtk_object_data_try_key() and gtk_object_data_force_id()
+to get an id from a string.
+</para>
+
+@object: object containing the associations.
+@data_id: quark of the key.
+@data: data to associate with that key.
+
+
+<!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
+<para>
+Just like gtk_object_set_data_full() except that it takes
+a #GQuark instead of a string, so it is slightly faster.
+</para>
+<para>
+Use gtk_object_data_try_key() and gtk_object_data_force_id()
+to get an id from a string.
+</para>
+
+@object: object containing the associations.
+@data_id: quark of the key.
+@data: data to associate with that key.
+@destroy: function to call when the association is destroyed.
+
+
+<!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
+<para>
+Just like gtk_object_get_data() except that it takes
+a #GQuark instead of a string, so it is slightly faster.
+</para>
+<para>
+Use gtk_object_data_try_key() and gtk_object_data_force_id()
+to get an id from a string.
+</para>
+
+@object: object containing the associations.
+@data_id: quark of the key.
+@Returns: the data if found, or NULL if no such data exists.
+
+
+<!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
+<para>
+Just like gtk_object_remove_data() except that it takes
+a #GQuark instead of a string, so it is slightly faster.
+</para>
+<para>
+Remove a specified datum from the object's data associations.
+Subsequent calls to gtk_object_get_data() will return NULL.
+</para>
+<para>
+Use gtk_object_data_try_key() and gtk_object_data_force_id()
+to get an id from a string.
+</para>
+
+@object: object containing the associations.
+@data_id: quark of the key.
+
+
+<!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
+<para>
+Just like gtk_object_remove_no_notify() except that it takes
+a #GQuark instead of a string, so it is slightly faster.
+</para>
+<para>
+Use gtk_object_data_try_key() and gtk_object_data_force_id()
+to get an id from a string.
+</para>
+
+@object: object containing the associations.
+@data_id: quark of the key.
+
+
+<!-- ##### MACRO gtk_object_data_try_key ##### -->
+<para>
+Sees whether a certain quark exists.
+Returns that quark if so.
+</para>
+<para>
+Although this is currently the same as g_quark_try_string(),
+it might someday be different, for example, if GQuarks
+and object data are converted to separate mechanisms,
+so it is good to use this macro.
+</para>
+
+
+
+<!-- ##### MACRO gtk_object_data_force_id ##### -->
+<para>
+Makes a quark from a string, possibly allocating a new quark.
+</para>
+<para>
+Although this is currently the same as g_quark_from_string(),
+it might someday be different, for example, if GQuarks
+and object data are converted to separate mechanisms,
+so it is good to use this macro.
+</para>
+
+
+
+<!-- ##### FUNCTION gtk_object_arg_set ##### -->
+<para>
+Private function to set an argument and argument info to an object.
+</para>
+
+@object: the object whose argument should be set.
+@arg: the argument.
+@info: infomation about this type of argument in general.
+
+
+<!-- ##### FUNCTION gtk_object_arg_get ##### -->
+<para>
+Private function to get an argument and argument info from an object.
+</para>
+
+@object: the object whose argument should be retrieved.
+@arg: the argument, for the name on input, the rest is filled on output.
+@info: a #GtkArgInfo structure to optionally fill in.
+
+
+<!-- ##### FUNCTION gtk_object_args_collect ##### -->
+<para>
+Private: Gets an array of #GtkArgs from a va_list C structure.
+</para>
+
+@object_type: the type of object to collect arguments for.
+@arg_list_p: pointer to be filled in with a list of parsed arguments.
+@info_list_p: optional pointer for a returned list #GtkArgInfos.
+@first_arg_name: name of first argument.
+@var_args: value of first argument, followed by more key/value pairs,
+terminated by NULL.
+@Returns: an error message, or NULL on success.
+It is the caller's responsibility to call g_free() in the event of error.
+
+
+<!-- ##### FUNCTION gtk_object_arg_get_info ##### -->
+<para>
+Query information about an argument type.
+</para>
+
+@object_type: type of object to query about.
+@arg_name: name of the argument.
+@info_p: pointer to be filled in with a pointer to the GtkArgInfo.
+@Returns: an error message, or NULL on success.
+It is the caller's responsibility to call g_free() in the event of error.
+
+
+<!-- ##### FUNCTION gtk_trace_referencing ##### -->
+<para>
+Private: print debugging information while doing a gtk_object_ref() or
+a gtk_object_unref().
+</para>
+
+@object: object to reference or unreference.
+@func: name of caller's function to print (used within macros).
+@dummy: unused.
+@line: line number (used within macros).
+@do_ref: whether to reference or unreference.
+
+
+<!-- ##### SIGNAL GtkObject::destroy ##### -->
+<para>
+Indicates that an object is being destroyed.
+</para>
+
+@object: the object which received the signal.
+
+<!-- ##### ARG GtkObject:user_data ##### -->
+<para>
+A pointer for convenience when programming applications.
+</para>
+
+<!-- ##### ARG GtkObject:signal ##### -->
+<para>
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object.
+</para>
+
+<!-- ##### ARG GtkObject:signal_after ##### -->
+<para>
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object, so that the signal is always run
+after other user handlers and the default handler.
+</para>
+
+<!-- ##### ARG GtkObject:object_signal ##### -->
+<para>
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object, so that the user data and objects
+and swapped when the signal handler is invoked.
+</para>
+<para>
+This is useful for handlers that are primarily notifying
+other objects and could just invoke an already existing function
+if the parameters were swapped.
+See gtk_signal_connect_object() for more details.
+</para>
+
+<!-- ##### ARG GtkObject:object_signal_after ##### -->
+<para>
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects
+the signal to the object, so that the user data and objects
+and swapped when the signal handler is invoked,
+and so that the handler is invoked after all others.
+</para>
+<para>
+See gtk_signal_connect_object_after() for more details.
+</para>
+
<para>
%%v - the current progress value.
</para>
+</listitem>
<listitem>
<para>
%%l - the lower bound for the progress value.
</para>
+</listitem>
<listitem>
<para>
%%u - the upper bound for the progress value.
</para>
+</listitem>
<listitem>
<para>
%%p - the current progress percentage.
</para>
+</listitem>
</itemizedlist>
</para>
Object methods and callbacks.
<!-- ##### SECTION Long_Description ##### -->
-<refsect2>\r
-<title>What are signals?</title>\r
-<para>\r
-Signals are a way to get notification when something happens\r
-and to customize object behavior according to the\r
-user's needs.\r
-Every <WordAsWord>signal</WordAsWord> is uniquely identified by a name,\r
-"class_name::signal_name", where signal_name might be something like\r
-"clicked" and class_name might be "GtkButton". Note that some other class\r
-may also define a "clicked" callback, so long as it doesn't derive from\r
-#GtkButton.\r
-</para>\r
-<para>\r
-When they are created, they are also assigned a unique positive integer,\r
-the signal id (1 is the first signal id- 0 is used to flag an error).\r
-Each is also tied to an array of types that describes\r
-the prototype of the function pointer(s) (handlers) you may\r
-connect to the signal. Finally, every signal has\r
-a default handler that is given by a function pointer\r
-in its class structure: it is run by default whenever the\r
-signal is emitted. (It is possible that a signal will\r
-be emitted and a user-defined handler will prevent the default handler\r
-from being run.)\r
-</para>\r
-<para>\r
-Signals are used by everyone, but they are only\r
-created on a per class basis-- so you should call\r
-call gtk_signal_new() unless you are writing\r
-a new #GtkObject type. However, if you want to make a new signal\r
-for an existing type, you may use gtk_object_class_user_signal_new()\r
-to create a signal that doesn't correspond to a class's builtin\r
-methods.\r
-</para>\r
-</refsect2>\r
-<refsect2>\r
-<title>How are signals used?</title>\r
-<para>\r
-There are two basic actions in the signal handling game.\r
-If you want notification of an event, you must <Emphasis>connect</Emphasis>\r
-a function pointer and a data pointer to that signal; the data pointer\r
-will be passed as the last argument to the function (so long as you\r
-are using the default marshalling functions).\r
-You will receive a connection id, a unique positive integer\r
-corresponding to that attachment.\r
-</para>\r
-<para>\r
-Functions that want to notify the user of certain actions,\r
-<Emphasis>emit</Emphasis> signals.\r
-</para>\r
-</refsect2>\r
-<refsect2>\r
-<title>Basic Terminology</title>\r
-<variablelist>\r
-\r
-<varlistentry>\r
-<term>signal</term>\r
-<listitem><para>A class method, e.g. GtkButton::clicked.\r
-More precisely it is a unique class-branch/signal-name pair.\r
-This means you may not define a signal handler for a class which\r
-derives from GtkButton that is called clicked,\r
-but it is okay to share signals names if they are separate in\r
-the class tree.\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>default handler</term>\r
-<listitem><para>The object's internal method which is invoked\r
-when the signal is emitted.</para>\r
-</listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>user-defined handler</term>\r
-<listitem><para>A function pointer and data connected\r
-to a signal (for a particular object).</para>\r
-<para>There are really two types: those which are connected\r
-normally, and those which are connected by one \r
-of the connect_after functions. The connect_after handlers\r
-are always run after the default handler.</para>\r
-<para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>\r
-</listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>emission</term>\r
-<listitem><para>the whole process of emitting a signal,\r
-including the invocation of all\r
-the different handler types mentioned above.</para>\r
-</listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>signal id</term>\r
-<listitem><para>The unique positive (nonzero) integer\r
-used to identify a signal. It can be used instead of \r
-a name to many functions for a slight performance\r
-improvement.</para>\r
-</listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>connection id</term>\r
-<listitem><para>The unique positive (nonzero) integer\r
-used to identify the connection of a user-defined handler\r
-to a signal. Notice that it is allowed to connect the\r
-same function-pointer/user-data pair twice, so\r
-there is no guarantee that a function-pointer/user-data\r
-maps to a unique connection id.\r
-</para>\r
-</listitem>\r
-</varlistentry>\r
-\r
-</variablelist>\r
-</refsect2>\r
-\r
-<refsect2><title>A brief note on how they work.</title>\r
-<para>\r
-The functions responsible for translating an array of #GtkArgs\r
-to your C compiler's normal semantics are called Marshallers.\r
-They are identified by\r
-gtk_marshal_return_value__parameter_list()\r
-for example a C function returning a gboolean and taking a gint\r
-can be invoked by using gtk_marshal_BOOL__INT().\r
-Not all possibly combinations of return/params are available,\r
-of course, so if you are writing a #GtkObject with parameters\r
-you might have to write a marshaller.\r
-</para>\r
+<refsect2>
+<title>What are signals?</title>
+<para>
+Signals are a way to get notification when something happens
+and to customize object behavior according to the
+user's needs.
+Every <WordAsWord>signal</WordAsWord> is uniquely identified by a name,
+"class_name::signal_name", where signal_name might be something like
+"clicked" and class_name might be "GtkButton". Note that some other class
+may also define a "clicked" callback, so long as it doesn't derive from
+#GtkButton.
+</para>
+<para>
+When they are created, they are also assigned a unique positive integer,
+the signal id (1 is the first signal id- 0 is used to flag an error).
+Each is also tied to an array of types that describes
+the prototype of the function pointer(s) (handlers) you may
+connect to the signal. Finally, every signal has
+a default handler that is given by a function pointer
+in its class structure: it is run by default whenever the
+signal is emitted. (It is possible that a signal will
+be emitted and a user-defined handler will prevent the default handler
+from being run.)
+</para>
+<para>
+Signals are used by everyone, but they are only
+created on a per class basis-- so you should call
+call gtk_signal_new() unless you are writing
+a new #GtkObject type. However, if you want to make a new signal
+for an existing type, you may use gtk_object_class_user_signal_new()
+to create a signal that doesn't correspond to a class's builtin
+methods.
+</para>
+</refsect2>
+<refsect2>
+<title>How are signals used?</title>
+<para>
+There are two basic actions in the signal handling game.
+If you want notification of an event, you must <Emphasis>connect</Emphasis>
+a function pointer and a data pointer to that signal; the data pointer
+will be passed as the last argument to the function (so long as you
+are using the default marshalling functions).
+You will receive a connection id, a unique positive integer
+corresponding to that attachment.
+</para>
+<para>
+Functions that want to notify the user of certain actions,
+<Emphasis>emit</Emphasis> signals.
+</para>
+</refsect2>
+<refsect2>
+<title>Basic Terminology</title>
+<variablelist>
+
+<varlistentry>
+<term>signal</term>
+<listitem><para>A class method, e.g. GtkButton::clicked.
+More precisely it is a unique class-branch/signal-name pair.
+This means you may not define a signal handler for a class which
+derives from GtkButton that is called clicked,
+but it is okay to share signals names if they are separate in
+the class tree.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>default handler</term>
+<listitem><para>The object's internal method which is invoked
+when the signal is emitted.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>user-defined handler</term>
+<listitem><para>A function pointer and data connected
+to a signal (for a particular object).</para>
+<para>There are really two types: those which are connected
+normally, and those which are connected by one
+of the connect_after functions. The connect_after handlers
+are always run after the default handler.</para>
+<para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>emission</term>
+<listitem><para>the whole process of emitting a signal,
+including the invocation of all
+the different handler types mentioned above.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>signal id</term>
+<listitem><para>The unique positive (nonzero) integer
+used to identify a signal. It can be used instead of
+a name to many functions for a slight performance
+improvement.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>connection id</term>
+<listitem><para>The unique positive (nonzero) integer
+used to identify the connection of a user-defined handler
+to a signal. Notice that it is allowed to connect the
+same function-pointer/user-data pair twice, so
+there is no guarantee that a function-pointer/user-data
+maps to a unique connection id.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+
+<refsect2><title>A brief note on how they work.</title>
+<para>
+The functions responsible for translating an array of #GtkArgs
+to your C compiler's normal semantics are called Marshallers.
+They are identified by
+gtk_marshal_return_value__parameter_list()
+for example a C function returning a gboolean and taking a gint
+can be invoked by using gtk_marshal_BOOL__INT().
+Not all possibly combinations of return/params are available,
+of course, so if you are writing a #GtkObject with parameters
+you might have to write a marshaller.
+</para>
</refsect2>
<!-- ##### SECTION See_Also ##### -->
-<para>\r
-<variablelist>\r
-\r
-<varlistentry>\r
-<term>#GtkObject</term>\r
-<listitem><para>The base class for things which emit signals.</para></listitem>\r
-</varlistentry>\r
-\r
-</variablelist>\r
+<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkObject</term>
+<listitem><para>The base class for things which emit signals.</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### MACRO GTK_SIGNAL_OFFSET ##### -->
<!-- ##### USER_FUNCTION GtkSignalMarshal ##### -->
-<para>\r
-This is currently a hack left in for a scheme wrapper library.\r
-It may be removed.\r
-</para>\r
-<para>\r
-Don't use it.\r
+<para>
+This is currently a hack left in for a scheme wrapper library.
+It may be removed.
+</para>
+<para>
+Don't use it.
</para>
@object: The object which emits the signal.
@nparams: The number of parameters to the function.
@args: The actual values of the arguments.
@arg_types: The types of the arguments.
-@return_type: The type of the return value from the function\r
+@return_type: The type of the return value from the function
or #GTK_TYPE_NONE for no return value.
<!-- ##### USER_FUNCTION GtkSignalDestroy ##### -->
-<para>\r
-A function which you can use to clean up when the\r
-signal handler is destroyed.\r
-</para>\r
-<para>\r
-For example, if your handler requires a few variables\r
-that you made into a struct and allocated (using g_new()\r
-or something), then you will probably want to free\r
-it as soon as the hook is destroyed. This will\r
-allow you to do that. (For this in particular\r
-it is convenient to pass g_free() as a #GtkSignalDestroy\r
-function).\r
-</para>
-
-@data: The user data associated with the hook that is being\r
+<para>
+A function which you can use to clean up when the
+signal handler is destroyed.
+</para>
+<para>
+For example, if your handler requires a few variables
+that you made into a struct and allocated (using g_new()
+or something), then you will probably want to free
+it as soon as the hook is destroyed. This will
+allow you to do that. (For this in particular
+it is convenient to pass g_free() as a #GtkSignalDestroy
+function).
+</para>
+
+@data: The user data associated with the hook that is being
destroyed.
<!-- ##### USER_FUNCTION GtkEmissionHook ##### -->
-<para>\r
-A simple function pointer to get invoked when the\r
-signal is emitted. This allows you tie a hook to the signal type,\r
-so that it will trap all emissions of that signal, from any object.\r
-</para>\r
-<para>\r
-You may not attach these to signals created with the\r
-#GTK_RUN_NO_HOOKS flag.\r
+<para>
+A simple function pointer to get invoked when the
+signal is emitted. This allows you tie a hook to the signal type,
+so that it will trap all emissions of that signal, from any object.
+</para>
+<para>
+You may not attach these to signals created with the
+#GTK_RUN_NO_HOOKS flag.
</para>
@object: the object which emits the signal.
@signal_id: the unique integer identify the signal type.
-@n_params: the number of parameters to the function,\r
+@n_params: the number of parameters to the function,
not including return value.
-@params: the parameters to the function. A pointer to\r
+@params: the parameters to the function. A pointer to
the return value is passed as a last element.
@data: the user data associated with the hook.
-@Returns: whether it wished to be removed. If it returns\r
+@Returns: whether it wished to be removed. If it returns
TRUE, the signal hook is disconnected (and destroyed).
<!-- ##### STRUCT GtkSignalQuery ##### -->
-<para>\r
-This structure contains all the information about a particular\r
-signal: its name, the type it affects, the signature of the handlers,\r
-and its unique identifying integer.\r
+<para>
+This structure contains all the information about a particular
+signal: its name, the type it affects, the signature of the handlers,
+and its unique identifying integer.
</para>
@object_type:
@params:
<!-- ##### ENUM GtkSignalRunType ##### -->
-<para>\r
-These configure the signal's emission. They control\r
-whether the signal can be emitted recursively on an object\r
-and\r
-whether to run the default method before or after the user-defined handlers.\r
-</para>\r
-\r
-<variablelist>\r
-\r
-<varlistentry>\r
-<term>GTK_RUN_FIRST</term>\r
-<listitem><para>Run the default handler before the connected user-defined\r
-handlers.\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>GTK_RUN_LAST</term>\r
-<listitem><para>Run the default handler after the connected\r
-user-defined handlers.\r
-(Handlers registered as "after" always run after the default handler though)\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>GTK_RUN_BOTH</term>\r
-<listitem><para>Run the default handler twice,\r
-once before the user-defined handlers,\r
-and\r
-once after.\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>GTK_RUN_NO_RECURSE</term>\r
-<listitem><para>Whether to prevent a handler or hook\r
-from reemitting the signal from within itself.\r
-Attempts to\r
-emit the signal while it is running will result in the signal\r
-emission being restarted once it is done with the current processing.\r
-</para><para>\r
-You must be\r
-careful to avoid having two handlers endlessly reemitting signals,\r
-gtk_signal_n_emissions() can be helpful.\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>GTK_RUN_ACTION</term>\r
-<listitem><para>The signal is an action you can \r
-invoke without any particular setup or cleanup.\r
-The signal is treated no differently, but some\r
-other code can determine if the signal is appropriate to\r
-delegate to user control. For example, key binding sets\r
-only allow bindings of ACTION signals to keystrokes.\r
-</para></listitem>\r
-</varlistentry>\r
-\r
-<varlistentry>\r
-<term>GTK_RUN_NO_HOOKS</term>\r
-<listitem><para>This prevents the connection of emission hooks\r
-to the signal.\r
-</para></listitem>\r
-</varlistentry>\r
-\r
+<para>
+These configure the signal's emission. They control
+whether the signal can be emitted recursively on an object
+and
+whether to run the default method before or after the user-defined handlers.
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term>GTK_RUN_FIRST</term>
+<listitem><para>Run the default handler before the connected user-defined
+handlers.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_LAST</term>
+<listitem><para>Run the default handler after the connected
+user-defined handlers.
+(Handlers registered as "after" always run after the default handler though)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_BOTH</term>
+<listitem><para>Run the default handler twice,
+once before the user-defined handlers,
+and
+once after.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_NO_RECURSE</term>
+<listitem><para>Whether to prevent a handler or hook
+from reemitting the signal from within itself.
+Attempts to
+emit the signal while it is running will result in the signal
+emission being restarted once it is done with the current processing.
+</para><para>
+You must be
+careful to avoid having two handlers endlessly reemitting signals,
+gtk_signal_n_emissions() can be helpful.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_ACTION</term>
+<listitem><para>The signal is an action you can
+invoke without any particular setup or cleanup.
+The signal is treated no differently, but some
+other code can determine if the signal is appropriate to
+delegate to user control. For example, key binding sets
+only allow bindings of ACTION signals to keystrokes.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_NO_HOOKS</term>
+<listitem><para>This prevents the connection of emission hooks
+to the signal.
+</para></listitem>
+</varlistentry>
+
</variablelist>
@GTK_RUN_FIRST:
<!-- ##### FUNCTION gtk_signal_new ##### -->
-<para>\r
-Create a new signal type. (This is usually done in the\r
-class initializer.)\r
+<para>
+Create a new signal type. (This is usually done in the
+class initializer.)
</para>
@name: the event name for the signal, e.g. "clicked".
-@signal_flags: a combination of GTK_RUN flags\r
-specifying detail of when the default handler is to be invoked.\r
-You should at least specify #GTK_RUN_FIRST\r
+@signal_flags: a combination of GTK_RUN flags
+specifying detail of when the default handler is to be invoked.
+You should at least specify #GTK_RUN_FIRST
or #GTK_RUN_LAST.
-@object_type: the type of object this signal pertains to.\r
+@object_type: the type of object this signal pertains to.
It will also pertain to derivers of this type automatically.
-@function_offset: How many bytes the function pointer is in\r
-the class structure for this type. Used to invoke a class\r
+@function_offset: How many bytes the function pointer is in
+the class structure for this type. Used to invoke a class
method generically.
-@marshaller: the function to translate between an array\r
-of GtkArgs and the native calling convention. Usually they\r
-are identified just by the type of arguments they take:\r
-for example, gtk_marshal_BOOL__STRING() describes a marshaller\r
+@marshaller: the function to translate between an array
+of GtkArgs and the native calling convention. Usually they
+are identified just by the type of arguments they take:
+for example, gtk_marshal_BOOL__STRING() describes a marshaller
which takes a string and returns a boolean value.
-@return_val: the type of return value, or GTK_TYPE_NONE for a signal\r
+@return_val: the type of return value, or GTK_TYPE_NONE for a signal
without a return value.
@nparams: the number of parameter the handlers may take.
@Varargs: a list of GTK_TYPE_*, one for each parameter.
<!-- ##### FUNCTION gtk_signal_newv ##### -->
-<para>\r
-Create a new signal type. (This is usually done in a\r
-class initializer.)\r
-</para>\r
-<para>\r
-This function take the types as an array, instead of a list\r
-following the arguments. Otherwise the same as gtk_signal_new().\r
+<para>
+Create a new signal type. (This is usually done in a
+class initializer.)
+</para>
+<para>
+This function take the types as an array, instead of a list
+following the arguments. Otherwise the same as gtk_signal_new().
</para>
@name: the name of the signal to create.
@signal_flags: see gtk_signal_new().
@object_type: the type of GtkObject to associate the signal with.
-@function_offset: how many bytes the function pointer is in\r
+@function_offset: how many bytes the function pointer is in
the class structure for this type.
@marshaller:
-@return_val: the type of the return value, or GTK_TYPE_NONE if\r
+@return_val: the type of the return value, or GTK_TYPE_NONE if
you don't want a return value.
@nparams: the number of parameters to the user-defined handlers.
-@params: an array of GtkTypes, describing the prototype to\r
+@params: an array of GtkTypes, describing the prototype to
the callbacks.
@Returns: the signal id.
<!-- ##### FUNCTION gtk_signal_lookup ##### -->
-<para>\r
-Given the name of the signal and the type of object it connects\r
-to, get the signal's identifying integer. Emitting the signal\r
-by number is somewhat faster than using the name each time.\r
-</para>\r
-<para>\r
-It also tries the ancestors of the given type.\r
+<para>
+Given the name of the signal and the type of object it connects
+to, get the signal's identifying integer. Emitting the signal
+by number is somewhat faster than using the name each time.
+</para>
+<para>
+It also tries the ancestors of the given type.
</para>
@name: the signal's name, e.g. clicked.
<!-- ##### FUNCTION gtk_signal_name ##### -->
-<para>\r
-Given the signal's identifier, find its name.\r
-</para>\r
-<para>\r
-Two different signals may have the same name, if they have differing types.\r
+<para>
+Given the signal's identifier, find its name.
+</para>
+<para>
+Two different signals may have the same name, if they have differing types.
</para>
@signal_id: the signal's identifying number.
<!-- ##### FUNCTION gtk_signal_emit ##### -->
-<para>\r
-Emit a signal. This causes the default handler and user-defined\r
-handlers to be run.\r
-</para>\r
-<para>\r
-Here is what gtk_signal_emit() does:\r
-</para>\r
-<para>\r
-1. Calls the default handler and the user-connected handlers.\r
-The default handler will be called first if\r
-GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.\r
-</para>\r
-<para>\r
-2. Calls all handlers connected with the "after" flag set.\r
+<para>
+Emit a signal. This causes the default handler and user-defined
+handlers to be run.
+</para>
+<para>
+Here is what gtk_signal_emit() does:
+</para>
+<para>
+1. Calls the default handler and the user-connected handlers.
+The default handler will be called first if
+GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.
+</para>
+<para>
+2. Calls all handlers connected with the "after" flag set.
</para>
@object: the object that emits the signal.
@signal_id: the signal identifier.
-@Varargs: the parameters to the function, followed\r
+@Varargs: the parameters to the function, followed
by a pointer to the return type, if any.
<!-- ##### FUNCTION gtk_signal_emit_by_name ##### -->
-<para>\r
-Emit a signal. This causes the default handler and user-connected\r
-handlers to be run.\r
+<para>
+Emit a signal. This causes the default handler and user-connected
+handlers to be run.
</para>
@object: the object that emits the signal.
@name: the name of the signal.
-@Varargs: the parameters to the function, followed\r
+@Varargs: the parameters to the function, followed
by a pointer to the return type, if any.
<!-- ##### FUNCTION gtk_signal_emitv ##### -->
-<para>\r
-Emit a signal. This causes the default handler and user-connected\r
-handlers to be run. This differs from gtk_signal_emit() by taking\r
-an array of GtkArgs instead of using C's varargs mechanism.\r
+<para>
+Emit a signal. This causes the default handler and user-connected
+handlers to be run. This differs from gtk_signal_emit() by taking
+an array of GtkArgs instead of using C's varargs mechanism.
</para>
@object: the object to emit the signal to.
@signal_id: the signal identifier.
-@params: an array of GtkArgs, one for each parameter,\r
+@params: an array of GtkArgs, one for each parameter,
followed by one which is a pointer to the return type.
<!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->
-<para>\r
-Emit a signal by name. This causes the default handler and user-connected\r
-handlers to be run. This differs from gtk_signal_emit() by taking\r
-an array of GtkArgs instead of using C's varargs mechanism.\r
+<para>
+Emit a signal by name. This causes the default handler and user-connected
+handlers to be run. This differs from gtk_signal_emit() by taking
+an array of GtkArgs instead of using C's varargs mechanism.
</para>
@object: the object to emit the signal to.
@name: the name of the signal.
-@params: an array of GtkArgs, one for each parameter,\r
+@params: an array of GtkArgs, one for each parameter,
followed by one which is a pointer to the return type.
<!-- ##### FUNCTION gtk_signal_n_emissions ##### -->
-<para>\r
-Find out the recursion depth of emissions for a particular type\r
-of signal and object. (So it will\r
-always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified)\r
-This is a way to avoid recursion: you can see if\r
-you are currently running in that signal handler and emit it only\r
-if you are.\r
-</para>\r
-<para>Another way to look at it is that this number increases\r
-by one when #gtk_signal_emit(), et al, are called,\r
-and decreases by one when #gtk_signal_emit() returns.\r
+<para>
+Find out the recursion depth of emissions for a particular type
+of signal and object. (So it will
+always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified)
+This is a way to avoid recursion: you can see if
+you are currently running in that signal handler and emit it only
+if you are.
+</para>
+<para>Another way to look at it is that this number increases
+by one when #gtk_signal_emit(), et al, are called,
+and decreases by one when #gtk_signal_emit() returns.
</para>
@object: the object with the signal handler.
@signal_id: the signal id.
-@Returns: the recursion depth of emissions of this signal for this\r
+@Returns: the recursion depth of emissions of this signal for this
object.
<!-- ##### FUNCTION gtk_signal_n_emissions_by_name ##### -->
-<para>\r
-Find out the recursion depth of emissions for a particular type\r
-of signal and object. Just like gtk_signal_n_emissions()\r
-except it will lookup the signal id for you.\r
+<para>
+Find out the recursion depth of emissions for a particular type
+of signal and object. Just like gtk_signal_n_emissions()
+except it will lookup the signal id for you.
</para>
@object: the object with the signal handler.
@name: the signal name.
-@Returns: the recursion depth of emissions of this signal for this\r
+@Returns: the recursion depth of emissions of this signal for this
object.
<!-- ##### FUNCTION gtk_signal_emit_stop ##### -->
-<para>\r
-This function aborts a signal's current emission.\r
-</para>\r
-<para>\r
-It will prevent the default method from running,\r
-if the signal was #GTK_RUN_LAST and you connected\r
-normally (i.e. without the "after" flag).\r
-<para>\r
-It will print a warning if used on a signal which\r
-isn't being emitted.\r
+<para>
+This function aborts a signal's current emission.
+</para>
+<para>
+It will prevent the default method from running,
+if the signal was #GTK_RUN_LAST and you connected
+normally (i.e. without the "after" flag).
+</para>
+<para>
+It will print a warning if used on a signal which
+isn't being emitted.
</para>
@object: the object whose signal handlers you wish to stop.
<!-- ##### FUNCTION gtk_signal_emit_stop_by_name ##### -->
-<para>\r
-This function aborts a signal's current emission.\r
-</para>\r
-<para>It is just like\r
-gtk_signal_emit_stop()\r
-except it will lookup the signal id for you.\r
+<para>
+This function aborts a signal's current emission.
+</para>
+<para>It is just like
+gtk_signal_emit_stop()
+except it will lookup the signal id for you.
</para>
@object: the object whose signal handlers you wish to stop.
<!-- ##### FUNCTION gtk_signal_connect ##### -->
-<para>\r
-Attach a function pointer and user data to a signal for\r
-a particular object.\r
-</para>\r
-<para>\r
-The GtkSignalFunction takes a <StructName>GtkObject</StructName> as its first parameter.\r
-It will be the same object as the one you're connecting\r
-the hook to. The func_data will be passed as the last parameter\r
-to the hook.\r
-</para>\r
-<para>\r
-All else being equal, signal handlers are invoked in the order \r
-connected (see gtk_signal_emit() for the other details of\r
-which order things are called in).\r
-</para>\r
-<para>\r
-Here is how one passes an integer as user data,\r
-for when you just want to specify a constant int\r
-as parameter to your function:\r
-<informalexample>\r
-<programlisting>\r
-static void button_clicked_int(GtkButton* button, gpointer func_data)\r
-{\r
- g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data));\r
-}\r
-\r
-/* By calling this function, you will make the g_print above\r
- * execute, printing the number passed as `to_print'. */\r
-static void attach_print_signal(GtkButton* button, gint to_print)\r
-{\r
- gtk_signal_connect(GTK_OBJECT(button), "clicked",\r
- GTK_SIGNAL_FUNC(button_clicked_int),\r
- GINT_TO_POINTER(to_print));\r
-}\r
-</programlisting>\r
+<para>
+Attach a function pointer and user data to a signal for
+a particular object.
+</para>
+<para>
+The GtkSignalFunction takes a <StructName>GtkObject</StructName> as its first parameter.
+It will be the same object as the one you're connecting
+the hook to. The func_data will be passed as the last parameter
+to the hook.
+</para>
+<para>
+All else being equal, signal handlers are invoked in the order
+connected (see gtk_signal_emit() for the other details of
+which order things are called in).
+</para>
+<para>
+Here is how one passes an integer as user data,
+for when you just want to specify a constant int
+as parameter to your function:
+</para>
+<informalexample>
+<programlisting>
+static void button_clicked_int(GtkButton* button, gpointer func_data)
+{
+ g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data));
+}
+
+/* By calling this function, you will make the g_print above
+ * execute, printing the number passed as `to_print'. */
+static void attach_print_signal(GtkButton* button, gint to_print)
+{
+ gtk_signal_connect(GTK_OBJECT(button), "clicked",
+ GTK_SIGNAL_FUNC(button_clicked_int),
+ GINT_TO_POINTER(to_print));
+}
+</programlisting>
</informalexample>
-@object: the object associated with the signal, e.g. if a button\r
+@object: the object associated with the signal, e.g. if a button
is getting pressed, this is that button.
@name: name of the signal.
@func: function pointer to attach to the signal.
<!-- ##### FUNCTION gtk_signal_connect_after ##### -->
-<para>\r
-Attach a function pointer and user data to a signal\r
-so that this handler will be called after the other handlers.\r
+<para>
+Attach a function pointer and user data to a signal
+so that this handler will be called after the other handlers.
</para>
@object: the object associated with the signal.
<!-- ##### FUNCTION gtk_signal_connect_object ##### -->
-<para>\r
-This function is for registering a callback that will\r
-call another object's callback. That is,\r
-instead of passing the object which is responsible\r
-for the event as the first parameter of the callback,\r
-it is switched with the user data (so the object which emits\r
-the signal will be the last parameter, which is where the\r
-user data usually is).\r
-</para>\r
-<para>\r
-This is useful for passing a standard function in as a callback.\r
-For example, if you wanted a button's press to gtk_widget_show()\r
-some widget, you could write:\r
-</para>\r
-<informalexample>\r
-<programlisting>\r
-gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);\r
-</programlisting>\r
+<para>
+This function is for registering a callback that will
+call another object's callback. That is,
+instead of passing the object which is responsible
+for the event as the first parameter of the callback,
+it is switched with the user data (so the object which emits
+the signal will be the last parameter, which is where the
+user data usually is).
+</para>
+<para>
+This is useful for passing a standard function in as a callback.
+For example, if you wanted a button's press to gtk_widget_show()
+some widget, you could write:
+</para>
+<informalexample>
+<programlisting>
+gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);
+</programlisting>
</informalexample>
@object: the object which emits the signal.
@name: the name of the signal.
@func: the function to callback.
-@slot_object: the object to pass as the first parameter to func.\r
-(Though it pretends to take an object, you can\r
+@slot_object: the object to pass as the first parameter to func.
+(Though it pretends to take an object, you can
really pass any gpointer as the #slot_object .)
@Returns: the connection id.
<!-- ##### FUNCTION gtk_signal_connect_object_after ##### -->
-<para>\r
-Attach a signal hook to a signal, passing in an alternate\r
-object as the first parameter, and guaranteeing \r
-that the default handler and all normal\r
-handlers are called first.\r
+<para>
+Attach a signal hook to a signal, passing in an alternate
+object as the first parameter, and guaranteeing
+that the default handler and all normal
+handlers are called first.
</para>
@object: the object associated with the signal.
<!-- ##### FUNCTION gtk_signal_connect_full ##### -->
-<para>\r
-Attach a function pointer and user data to a signal with\r
-more control.\r
+<para>
+Attach a function pointer and user data to a signal with
+more control.
</para>
-@object: the object which emits the signal. For example, a button\r
+@object: the object which emits the signal. For example, a button
in the button press signal.
@name: the name of the signal.
@func: function pointer to attach to the signal.
-@marshal: the function marshal, see the gtkmarshall documentation for\r
-more details, but briefly: the marshaller is a function which takes\r
-the #GtkObject which emits the signal, the user data, the number of the\r
-arguments, and the array of arguments. It is responsible for\r
-calling the function in the appropriate calling convention.\r
-gtk_signal_default_marshaller is usually fine.\r
-(This shows up, for example, when worrying about matching\r
+@marshal: the function marshal, see the gtkmarshall documentation for
+more details, but briefly: the marshaller is a function which takes
+the #GtkObject which emits the signal, the user data, the number of the
+arguments, and the array of arguments. It is responsible for
+calling the function in the appropriate calling convention.
+gtk_signal_default_marshaller is usually fine.
+(This shows up, for example, when worrying about matching
c++ or other languages' calling conventions.)
@data: the user data associated with the function.
-@destroy_func: function to call when this particular hook is \r
+@destroy_func: function to call when this particular hook is
disconnected.
-@object_signal: whether this is an object signal-- basically an "object\r
-signal" is one that wants its user_data and object fields switched,\r
-which is useful for calling functions which operate on another\r
+@object_signal: whether this is an object signal-- basically an "object
+signal" is one that wants its user_data and object fields switched,
+which is useful for calling functions which operate on another
object primarily.
-@after: whether to invoke the user-defined handler after the signal, or to let \r
-the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST\r
+@after: whether to invoke the user-defined handler after the signal, or to let
+the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST
and #GTK_RUN_LAST).
@Returns: the connection id.
<!-- ##### FUNCTION gtk_signal_connect_while_alive ##### -->
-<para>\r
-Attach a function pointer and another GtkObject to a signal.\r
-</para>\r
-<para>\r
-This function takes an object whose "destroy" signal\r
-should be trapped.\r
-That way, you don't have to clean up the\r
-signal handler when you destroy the object.\r
-It is a little less efficient though.\r
-</para>\r
-<para>\r
-(Instead you may call gtk_signal_disconnect_by_data(), if you want\r
-to explicitly delete all attachments to this object. This\r
-is perhaps not recommended since it could be confused\r
-with an integer masquerading as a pointer (through GINT_AS_POINTER).)\r
+<para>
+Attach a function pointer and another GtkObject to a signal.
+</para>
+<para>
+This function takes an object whose "destroy" signal
+should be trapped.
+That way, you don't have to clean up the
+signal handler when you destroy the object.
+It is a little less efficient though.
+</para>
+<para>
+(Instead you may call gtk_signal_disconnect_by_data(), if you want
+to explicitly delete all attachments to this object. This
+is perhaps not recommended since it could be confused
+with an integer masquerading as a pointer (through GINT_AS_POINTER).)
</para>
@object: the object that emits the signal.
@signal:
@func: function pointer to attach to the signal.
@func_data: pointer to pass to func.
-@alive_object: object whose death should cause the handler connection\r
+@alive_object: object whose death should cause the handler connection
to be destroyed.
<!-- # Unused Parameters # -->
@name: name of the signal.
<!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
-<para>\r
-These signal connectors are for signals which refer to objects,\r
-so they must not be called after the object is deleted.\r
-</para>\r
-<para>\r
-Unlike gtk_signal_connect_while_alive(),\r
-this swaps the object and user data, making it suitable for\r
-use with functions which primarily operate on the user data.\r
-</para>\r
-<para>\r
-This function acts just like gtk_signal_connect_object() except\r
-it traps the "destroy" signal to prevent you from having to\r
-clean up the handler.\r
+<para>
+These signal connectors are for signals which refer to objects,
+so they must not be called after the object is deleted.
+</para>
+<para>
+Unlike gtk_signal_connect_while_alive(),
+this swaps the object and user data, making it suitable for
+use with functions which primarily operate on the user data.
+</para>
+<para>
+This function acts just like gtk_signal_connect_object() except
+it traps the "destroy" signal to prevent you from having to
+clean up the handler.
</para>
@object: the object associated with the signal.
@signal:
@func: function pointer to attach to the signal.
-@alive_object: the user data, which must be an object, whose destruction\r
+@alive_object: the user data, which must be an object, whose destruction
should signal the removal of this signal.
<!-- # Unused Parameters # -->
@name: name of the signal.
<!-- ##### FUNCTION gtk_signal_disconnect ##### -->
-<para>\r
-Destroy a user-defined handler connection.\r
+<para>
+Destroy a user-defined handler connection.
</para>
@object: the object which the handler pertains to.
<!-- ##### FUNCTION gtk_signal_disconnect_by_func ##### -->
-<para>\r
-Destroy all connections for a particular object, with\r
-the given function-pointer and user-data.\r
+<para>
+Destroy all connections for a particular object, with
+the given function-pointer and user-data.
</para>
@object: the object which emits the signal.
<!-- ##### FUNCTION gtk_signal_disconnect_by_data ##### -->
-<para>\r
-Destroy all connections for a particular object, with\r
-the given user-data.\r
+<para>
+Destroy all connections for a particular object, with
+the given user-data.
</para>
@object: the object which emits the signal.
<!-- ##### FUNCTION gtk_signal_handler_block ##### -->
-<para>\r
-Prevent an user-defined handler from being invoked. All other\r
-signal processing will go on as normal, but this particular\r
-handler will ignore it.\r
+<para>
+Prevent an user-defined handler from being invoked. All other
+signal processing will go on as normal, but this particular
+handler will ignore it.
</para>
@object: the object which emits the signal to block.
<!-- ##### FUNCTION gtk_signal_handler_block_by_func ##### -->
-<para>\r
-Prevent a user-defined handler from being invoked, by reference to\r
-the user-defined handler's function pointer and user data. (It may result in\r
-multiple hooks being blocked, if you've called connect multiple times.)\r
+<para>
+Prevent a user-defined handler from being invoked, by reference to
+the user-defined handler's function pointer and user data. (It may result in
+multiple hooks being blocked, if you've called connect multiple times.)
</para>
@object: the object which emits the signal to block.
<!-- ##### FUNCTION gtk_signal_handler_block_by_data ##### -->
-<para>\r
-Prevent all user-defined handlers with a certain user data from being invoked.\r
+<para>
+Prevent all user-defined handlers with a certain user data from being invoked.
</para>
@object: the object which emits the signal we want to block.
<!-- ##### FUNCTION gtk_signal_handler_unblock ##### -->
-<para>\r
-Undo a block, by connection id. Note that undoing a block doesn't\r
-necessarily make the hook callable, because if you block a\r
-hook twice, you must unblock it twice.\r
+<para>
+Undo a block, by connection id. Note that undoing a block doesn't
+necessarily make the hook callable, because if you block a
+hook twice, you must unblock it twice.
</para>
@object: the object which emits the signal we want to unblock.
-@handler_id: the emission handler identifier, as returned by\r
+@handler_id: the emission handler identifier, as returned by
gtk_signal_connect(), etc.
<!-- ##### FUNCTION gtk_signal_handler_unblock_by_func ##### -->
-<para>\r
-Undo a block, by function pointer and data.\r
-Note that undoing a block doesn't\r
-necessarily make the hook callable, because if you block a\r
-hook twice, you must unblock it twice.\r
+<para>
+Undo a block, by function pointer and data.
+Note that undoing a block doesn't
+necessarily make the hook callable, because if you block a
+hook twice, you must unblock it twice.
</para>
@object: the object which emits the signal we want to unblock.
<!-- ##### FUNCTION gtk_signal_handler_unblock_by_data ##### -->
-<para>\r
-Undo block(s), to all signals for a particular object\r
-with a particular user-data pointer\r
+<para>
+Undo block(s), to all signals for a particular object
+with a particular user-data pointer
</para>
@object: the object which emits the signal we want to unblock.
<!-- ##### FUNCTION gtk_signal_handler_pending ##### -->
-<para>\r
-Returns a connection id corresponding to a given signal id and object.\r
-</para>\r
-<para>\r
-One example of when you might use this is when the arguments\r
-to the signal are difficult to compute. A class implementor\r
-may opt to not emit the signal if no one is attached anyway,\r
-thus saving the cost of building the arguments.\r
+<para>
+Returns a connection id corresponding to a given signal id and object.
+</para>
+<para>
+One example of when you might use this is when the arguments
+to the signal are difficult to compute. A class implementor
+may opt to not emit the signal if no one is attached anyway,
+thus saving the cost of building the arguments.
</para>
@object: the object to search for the desired user-defined handler.
@signal_id: the number of the signal to search for.
-@may_be_blocked: whether it is acceptable to return a blocked\r
+@may_be_blocked: whether it is acceptable to return a blocked
handler.
@Returns: the connection id, if a connection was found. 0 otherwise.
<!-- ##### FUNCTION gtk_signal_handler_pending_by_func ##### -->
-<para>\r
-Returns a connection id corresponding to a given signal id, object, function\r
-pointer and user data.\r
+<para>
+Returns a connection id corresponding to a given signal id, object, function
+pointer and user data.
</para>
@object: the object to search for the desired handler.
@signal_id: the number of the signal to search for.
-@may_be_blocked: whether it is acceptable to return a blocked\r
+@may_be_blocked: whether it is acceptable to return a blocked
handler.
@func: the function pointer to search for.
@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_handler_pending_by_id ##### -->
-<para>\r
-Returns whether a connection id is valid (and optionally not blocked).\r
+<para>
+Returns whether a connection id is valid (and optionally not blocked).
</para>
@object: the object to search for the desired handler.
@handler_id: the connection id.
-@may_be_blocked: whether it is acceptable to return a blocked\r
+@may_be_blocked: whether it is acceptable to return a blocked
handler.
-@Returns: TRUE if the signal exists and wasn't blocked,\r
+@Returns: TRUE if the signal exists and wasn't blocked,
unless #may_be_blocked was specified. FALSE otherwise.
<!-- ##### FUNCTION gtk_signal_handlers_destroy ##### -->
-<para>\r
-Destroy all the signal handlers connected to an object.\r
-This is done automatically when the object is destroyed.\r
-</para>\r
-<para>\r
-This function is labeled private.\r
+<para>
+Destroy all the signal handlers connected to an object.
+This is done automatically when the object is destroyed.
+</para>
+<para>
+This function is labeled private.
</para>
@object: the object whose signal handlers should be destroyed.
<!-- ##### FUNCTION gtk_signal_set_funcs ##### -->
-<para>\r
-These set default functions to call when the user didn't\r
-supply a function when connecting. (These are rarely\r
-used, and probably only for language bindings)\r
-</para>\r
-<para>\r
-By default, there are no such functions.\r
+<para>
+These set default functions to call when the user didn't
+supply a function when connecting. (These are rarely
+used, and probably only for language bindings)
+</para>
+<para>
+By default, there are no such functions.
</para>
-@marshal_func: the function to invoke on every handlers for which there\r
+@marshal_func: the function to invoke on every handlers for which there
isn't a function pointer. May be NULL.
-@destroy_func: the function to invoke when each hook is destroyed.\r
+@destroy_func: the function to invoke when each hook is destroyed.
May be NULL.
<!-- ##### FUNCTION gtk_signal_query ##### -->
-<para>\r
-Obtain information about a signal.\r
+<para>
+Obtain information about a signal.
</para>
@signal_id: the signal type identifier.
-@Returns: a pointer to a GtkSignalQuery structure\r
-which contains all the information, or NULL.\r
+@Returns: a pointer to a GtkSignalQuery structure
+which contains all the information, or NULL.
The pointer is allocated just for you: you must g_free() it.
<!-- ##### FUNCTION gtk_signal_add_emission_hook ##### -->
-<para>\r
-Add an emission hook for a type of signal, for any object.\r
+<para>
+Add an emission hook for a type of signal, for any object.
</para>
@signal_id: the type of signal to hook for.
@hook_func: the function to invoke to handle the emission hook.
@data: the user data passed in to hook_func.
-@Returns: the id (that you may pass as a parameter\r
+@Returns: the id (that you may pass as a parameter
to gtk_signal_remove_emission_hook()).
<!-- ##### FUNCTION gtk_signal_add_emission_hook_full ##### -->
-<para>\r
-Add an emission hook for a type of signal, for any object.\r
-(with control of what happens when the hook is\r
-destroyed).\r
+<para>
+Add an emission hook for a type of signal, for any object.
+(with control of what happens when the hook is
+destroyed).
</para>
@signal_id: the type of signal add the hook for.
@hook_func: the function to invoke to handle the hook.
@data: the user data passed in to hook_func.
-@destroy: a function to invoke when the hook is destroyed,\r
-to clean up any allocation done just for this\r
+@destroy: a function to invoke when the hook is destroyed,
+to clean up any allocation done just for this
signal handler.
-@Returns: the id (that you may pass as a parameter\r
+@Returns: the id (that you may pass as a parameter
to gtk_signal_remove_emission_hook()).
<!-- ##### FUNCTION gtk_signal_remove_emission_hook ##### -->
-<para>\r
-Delete an emission hook. (see gtk_signal_add_emission_hook())\r
+<para>
+Delete an emission hook. (see gtk_signal_add_emission_hook())
</para>
@signal_id: the id of the signal type.
projects / gtk4.git / commitdiff